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

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 values i infra (każdy jako deklaracja JSON Schema 2020-12 w formie zwięzłej lub pełnej), kontrakt wyjściowy provides, kontrakt krawędzi przychodzących usesSchema oraz 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 values i infra (każdy jako deklaracja JSON Schema 2020-12), selektory dołączenia appliesTo oraz 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 blok provides, 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, parser lub importer — 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 w spec.provider.capabilities i przenosi metadane gniazda dostawcy — workloadSchema i wellKnownAnnotations — w tym samym bloku spec.provider.
  • Manifest — tabela mapowań dla projektu. Wiąże abstrakcyjne typy Component i Feature z konkretnymi URI encji Recipe i FeatureRecipe, w sekcjach components i features, z kolejnością wyszukiwania name > wersjonowany type > niewersjonowany type.
  • 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.