Przegląd dokumentacji encji
Słownik autorski Aggrega obejmuje Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary i ArtifactLibrary — a także należący do platformy rodzaj Workload, osadzony w syntetyzowanym wejściu encji Recipe. Każda encja jest dokumentem YAML zgodnym z JSON Schema; każde pole, słowo kluczowe i odwołanie między encjami opisane w tej dokumentacji jest częścią tego kontraktu autorskiego.
Ten zestaw rozdziałów obejmuje powierzchnię autorską: jakie pola przyjmuje każda encja, co każde pole oznacza dla autora i jak pola współdziałają między encjami (implements: encji Recipe wskazujące encję Component, którą ona implementuje, wskaźnik manifest: encji Release na encję Manifest, pole containers.<name>.attachments encji Workload odwołujące się do slotów zadeklarowanych w featuresSchema encji Component). Koncepcyjna rola każdej encji — dlaczego taksonomia ma taki kształt, która domena jest właścicielem której encji, jak Cztery Domeny rozdzielają zagadnienia autorskie — jest opisana w ../architecture/04-entity-taxonomy.md. Architektoniczna rola rodzaju Workload jako jednego z trzech rodzajów wejścia encji Recipe jest opisana w ../architecture/16-recipe-input-composition.md.
Jak zorganizowana jest ta dokumentacja
Słownik autorski dokumentują dwie powierzchnie, które odpowiadają na różne pytania.
Każdy z wymienionych wyżej rodzajów ma generowaną dokumentację schematu. Strony te są generowane ze schematów publikowanych przez sam kompilator, a schema/README.md indeksuje cały zestaw — rodzaje encji, kształty komunikacji wtyczek i pliki przestrzeni roboczej. Dokumentacja schematu odpowiada na pytanie „co może zawierać ten dokument”: każde pole, jego typ, czy jest wymagane i ograniczenia wymuszane przez kopertę.
Poniższe strony to przewodniki autorskie. Są pisane ręcznie, aby przekazać to, czego schemat nie potrafi: do czego służy dany rodzaj, jak jego pola współdziałają z innymi rodzajami, który kształt autorski pasuje do której sytuacji oraz jakich konwencji przestrzega katalog biblioteki standardowej. Przewodnik autorski odpowiada na pytanie „jak to napisać i dlaczego ma taki kształt”.
Dokumentacja poszczególnych encji
- Aggregate — deklaratywny artefakt intencji programisty. Deklaruje komponenty, ich topologię za pomocą
uses, kontrakty parametrów dla zmienności między środowiskami oraz dołączenia encji Feature. - Component — encja katalogowa tworzona przez Architekta Platformy, definiująca wielokrotnego użytku rodzaj komponentu. Deklaruje swoje schematy
valuesiinfra(każdy jako deklaracja JSON Schema 2020-12 w formie zwięzłej lub pełnej), kontrakt wyjściowyprovides, kontrakt krawędzi przychodzącychusesSchemaoraz sloty poświadczeń za pomocąfeaturesSchema. - Feature — encja katalogowa tworzona przez Architekta Platformy dla zagadnienia przekrojowego (sidecar monitorujący, maskowanie danych, polityka routingu). Deklaruje swoje schematy
valuesiinfra(każdy jako deklaracja JSON Schema 2020-12), selektory dołączeniaappliesTooraz ograniczenia interoperacyjności. - Recipe — tworzone przez zespół Ops tłumaczenie encji Component na konkretnego dostawcę. Łączy trzy rodzaje wejścia (
source:+valuesMapping:,workload:,artifacts:— każdy przyjmuje treść inline lub$import:zgodnie z ujednoliconym słownikiem importu plików) oraz blokprovides, który tworzy kontrakt wstrzykiwania po stronie wywołującego. - FeatureRecipe — tworzone przez zespół Ops tłumaczenie encji Feature na konkretnego dostawcę. Używa tego samego kontraktu trzech rodzajów wejścia co Recipe oraz
injectMapping, które przechwytuje potok wstrzykiwania w celu przepisywania zmiennych po stronie wywołującego. - Plugin — wtyczka WebAssembly adresowana treścią. Deklaruje jeden typ gniazda, który implementuje —
provider,linter,pipeline-step,governance,cli,parserlubimporter— swoją wersję ABI oraz możliwości obsługiwane przez ten typ gniazda. Encja Plugin renderująca dla dostawcy (pluginType: provider) deklaruje nazwy obsługiwanych dostawców wspec.provider.capabilitiesi przenosi metadane gniazda dostawcy —workloadSchemaiwellKnownAnnotations— w tym samym blokuspec.provider. - Manifest — tabela mapowań dla projektu. Wiąże abstrakcyjne typy Component i Feature z konkretnymi URI encji Recipe i FeatureRecipe, w sekcjach
componentsifeatures, z kolejnością wyszukiwanianame> wersjonowanytype> niewersjonowanytype. - Release — router wdrożeń dla środowiska. Wiąże encję Aggregate z encją Manifest, mapuje komponenty na granice fizyczne, dostarcza wartości parametrów dla środowiska i dołącza zarządzane przez Ops encje Features.
Encje bibliotek
Cztery rodzaje bibliotek należą do poziomu 3 — opcjonalnych encji wielokrotnego użytku. Katalog deklaruje bibliotekę, gdy ta sama treść powtarza się w jego encjach, a w przeciwnym razie obywa się bez nich. Każda zawiera jeden typ treści, a fragment w odwołaniu (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) wskazuje, do której biblioteki odwołanie się odnosi.
- SchemaLibrary — definicje JSON Schema 2020-12 wielokrotnego użytku wraz z opcjonalnymi sparametryzowanymi pomocnikami, do których schematy encji Component lub Feature odwołują się przez
$ref: <Library>#/schemas/<name>. - MappingLibrary — fragmenty szablonów Go wielokrotnego użytku, importowane do
valuesMapping:encji Recipe lub FeatureRecipe przez$import: <Library>#/mappings/<name>. - WorkloadLibrary — treść Workload wielokrotnego użytku, importowana do
workload:encji Recipe lub FeatureRecipe przez$import: <Library>#/workloads/<name>. - ArtifactLibrary — pakiety pomocniczych plików wyjściowych wielokrotnego użytku, importowane do
artifacts:encji Recipe lub FeatureRecipe przez$import: <Library>#/artifacts/<name>. Pakiet jest jednostką ponownego użycia: jeden import rozwija się w jedno wyjście na każdy plik w pakiecie.
Rodzaje należące do platformy
- Workload — należący do platformy rodzaj kompilatora (nie jest encją katalogową tworzoną przez użytkownika). Osadzany w polu
workload:encji Recipe (inline lub przez$import:); opisuje kształt wdrożenia, który dostawca syntetyzuje w natywne manifesty dostawcy.