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

Schemat Aggrega Release

Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.

Identyfikator schematu: https://aggrega.ai/schemas/release-v1beta1.schema.json

Opisowe wskazówki dotyczące tworzenia encji Release zawiera dokumentacja tworzenia encji Release; ta strona dokumentuje schemat strukturalny, który ta dokumentacja opisuje.

Typ najwyższego poziomu: object

Właściwości

WłaściwośćTypWymaganaOpis
apiVersionconst “aggrega.ai/v1beta1”takStała: "aggrega.ai/v1beta1"
kindconst “Release”takStała: "Release"
metadataobjecttak
specobjecttakTo, co encja Release wiąże i kieruje: encja Aggregate i encja Manifest, które wdraża (lub baza extends), zależne od środowiska wypełnienie parametrów oraz granice, do których kierowane są jej komponenty.

Dodatkowe właściwości są niedozwolone.

release.metadata

WłaściwośćTypWymaganaOpis
namestringtakCo najmniej 1 znak.
environmentstringtak
versionstringtakWersja wydania w ścisłym formacie Semantic Versioning (np. 1.0.0). Wzorzec: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
descriptionstringnieCzym jest ta encja i do czego służy, napisane dla osoby decydującej, czy jej użyć. Należy zacząć od zdania nazywającego rzecz, a następnie dodać to, czego czytelnik potrzebuje, aby ją wybrać i poprawnie jej użyć — czego oczekuje od platformy, na którą jest wdrażana, i co w jej zachowaniu może zaskoczyć. Zwykle wystarcza krótki akapit.
maintainersobject[]nieLista opiekunów, do których należy ta encja.
licensestringnieIdentyfikator SPDX licencji oprogramowania opisywanego przez tę encję, np. MIT lub AGPL-3.0. Określa warunki tego oprogramowania, a nie warunki tego pliku.
repositorystringnieURL repozytorium Git, w którym znajdują się pliki źródłowe.
homestringnieURL strony domowej, wiki lub dokumentacji tej encji.
keywordsstring[]nieLista opisowych słów kluczowych ułatwiających wyszukiwanie w interfejsie użytkownika.

Dodatkowe właściwości są niedozwolone.

release.metadata.maintainers[]
WłaściwośćTypWymaganaOpis
namestringtak
emailstringnie
urlstringnie

Dodatkowe właściwości są niedozwolone.

release.spec

To, co encja Release wiąże i kieruje: encja Aggregate i encja Manifest, które wdraża (lub baza extends), zależne od środowiska wypełnienie parametrów oraz granice, do których kierowane są jej komponenty.

WłaściwośćTypWymaganaOpis
aggregatestringnieOdwołanie do encji Aggregate (intencji dewelopera, Developer Intent), którą to wydanie wdraża. Sam token jest rozwiązywany według tożsamości — metadata.name wskazanej encji Aggregate, wyszukiwanej w katalogu własnym encji Release, a następnie w katalogu (catalog). Wartość zaczynająca się od ’./’ lub ’../’ to jawny plik lokalny rozwiązywany względem encji Release (np. ’../shared/app.yaml’, aby współdzielić jedną encję Aggregate między wariantami wydania w podkatalogu).
manifeststringnieOdwołanie do encji Manifest rozwiązującej abstrakcyjne interfejsy, względem których to wydanie jest wdrażane. Sam token jest rozwiązywany według tożsamości — metadata.name wskazanej encji Manifest, wyszukiwanej w katalogu własnym encji Release. Wartość zaczynająca się od ’./’ lub ’../’ to jawny plik lokalny rozwiązywany względem encji Release. Encja Manifest należy do strony wdrożenia i nie jest indeksowana w katalogu (catalog), więc jest rozwiązywana wyłącznie z katalogu encji Release lub z jawnej ścieżki.
extendsstringnieOdwołanie do bazowej encji Release, której powierzchnię autorską dziedziczy ta encja Release — jej drzewo granic wraz z przypisaną do poszczególnych komponentów infrastrukturą (infra) i dołączonymi encjami Feature, jej parametry, adnotacje oraz wskaźnik na encję Manifest. Wartość jest ścieżką do pliku obok tej encji Release, zaczynającą się od ’./’ lub ’../’; sama nazwa i współrzędne rejestru są odrzucane, ponieważ encja Release należy do strony wdrożenia i nie jest indeksowana w katalogu (catalog). To, co odziedziczone, można zastępować klucz po kluczu, aż do pierwszej niepodzielnej wartości — skalara, listy, szablonu — która jest zastępowana w całości; klucz zapisany jako null usuwa to, co odziedziczone. Żadne pole metadata nie jest przenoszone, więc potomek ma własną nazwę, wersję i środowisko. Zadeklarowanie ‘aggregate’ obok ‘extends’ jest odrzucane przez ten schemat, więc potomek wdraża tę samą intencję dewelopera (Developer Intent) co jego baza; ‘manifest’ pozostaje opcjonalne i można je nadpisać, aby podmienić plik blokady zależności.
parametersobjectnieZależny od środowiska kontrakt wypełniania zmiennych z dwoma trybami tworzenia, wybieranymi na podstawie kształtu treści. Tryb 1 (inline): mapa YAML zawierająca bezpośrednio ustrukturyzowane, zagnieżdżone wartości parametrów. Tryb 2 (import pliku): mapa YAML z dokładnie jednym kluczem, $import: ./relative/path.yaml, wskazującym pojedynczy plik lokalny dostarczający wartości parametrów. W tym miejscu dozwolone jest tylko jedno źródło — warstwowanie wielu plików należy do łańcuchów extends: encji Release (nadrzędna encja Release dostarcza bazowe parametry; potomna rozszerza je i nadpisuje).
boundariesmapa boundarynieGłówne logiczne pojemniki, do których kierowane są komponenty encji Aggregate. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
componentsmapa boundary_componentnieInstancje komponentów najwyższego poziomu z przypisaną do poszczególnych komponentów infrastrukturą operatora, dla jednozakresowej encji Release bez nazwanych granic. Wzajemnie wykluczające się z boundaries: należy zadeklarować components dla płaskiej encji Release albo boundaries dla routingu do wielu celów, nigdy oba. Gdy użyto components, kompilator syntetyzuje granicę default, która je zawiera, i emituje ich artefakty płasko do dist/. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.

Dodatkowe właściwości są niedozwolone.

Definicje

boundary_component

Instancja komponentu skierowana do granicy, z opcjonalnym fizycznym wymiarowaniem i dołączonymi funkcjami.

WłaściwośćTypWymaganaOpis
descriptionstringnieOpcjonalna dokumentacja opisująca rolę tego komponentu w tej granicy encji Release.
subDirectorystringnieNadpisanie podścieżki na poziomie Component, dołączane do katalogu nadrzędnej granicy. Jeśli zostanie pominięte lub będzie puste zarówno w granicy, jak i w komponencie, domyślnie przyjmuje wartość ’{{ .capability }}’; pusty ciąg wpisany tutaj jest traktowany jak pominięcie. Aby wyłączyć generowanie podkatalogów, należy ustawić ’.’ lub szablon, który daje w wyniku pusty ciąg.
annotationsmapa string lub object lub nullnieAdnotacje operatora specyficzne dla Component, które nadpisują adnotacje na poziomie granicy dla tego komponentu. Są głęboko scalane z adnotacjami granicy (przy kolizji kluczy wygrywa komponent; wartości strukturalne są scalane według podkluczy ze strukturalnymi wartościami nadrzędnymi). Wartości to ciągi znaków, obiekty strukturalne lub null. Służą do nadpisywania dla poszczególnych komponentów dobrze znanych adnotacji dostawcy (np. aggrega.ai/namespace u dostawcy helm). Jawne null przy kluczu odziedziczonym z nadrzędnej granicy usuwa odziedziczone powiązanie z tego komponentu (rezygnacja z encji Feature sterowanej adnotacjami); komponenty równorzędne zachowują odziedziczone powiązanie.
infraobjectnieFizyczne wymiarowanie ściśle lokalne dla tego komponentu (np. repliki, IOPS dysku).
featuresmapa objectnieEncje Features dołączone do tego komponentu przez encję Release. Dla funkcji zadeklarowanych także w encji Aggregate podawane jest tylko infra (wartości pochodzą z encji Aggregate). Dla funkcji występujących tylko w encji Release (wstrzykiwanych przez operatora) type jest wymagany. Klucze są nazwami instancji funkcji i mogą zawierać pełny URI typu funkcji (kropki i ukośniki są dozwolone). Encja Release NIE MOŻE podawać wartości dla funkcji — to domena dewelopera. Klucze: co najmniej jedna litera, cyfra, podkreślenie, kropka, ukośnik lub łącznik. Wzorzec: ^[a-zA-Z0-9_./-]+$.
usesrelease_uses_blockniePowierzchnia krawędzi operatora. W obrębie gniazd zadeklarowanych przez architekta encja Release może podłączyć zadeklarowane, ale niepowiązane gniazdo do istniejącego komponentu (target) lub podać infra dla krawędzi, albo jedno i drugie. Bez wartości (obowiązuje zakaz values: w encji Release) i bez tworzenia zasobów obliczeniowych; przekierowanie krawędzi zadeklarowanej przez dewelopera zatrzymuje budowanie.

Dodatkowe właściwości są niedozwolone.

release_uses_block

Tworzona w encji Release powierzchnia uses dla poszczególnych krawędzi, kluczowana najpierw gniazdem, a potem aliasem (odzwierciedla kształt topologii uses encji Aggregate). Każde połączenie może ustawić target (aby utworzyć krawędź do zadeklarowanego, ale niepowiązanego gniazda, wskazującą istniejący komponent), infra (konfigurację operatora dla krawędzi, walidowaną względem infraSchema gniazda podczas rozwiązywania encji Release) i features (dołączenia wypełniające sloty deklarowane przez gniazdo), w dowolnej kombinacji. values jest zabronione (zakaz values: w encji Release); przekierowanie krawędzi zadeklarowanej przez dewelopera jest głośnym zabezpieczeniem podczas budowania.

Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.

Wartości są typu map of object.

Żadne inne klucze nie są dozwolone.

release_connection_attachment

Pojedyncze dołączenie zawarte we wpisie połączenia encji Release: encja Feature wypełniająca slot deklarowany przez gniazdo połączenia, wraz z wymiarowaniem nadanym jej przez operatora.

WłaściwośćTypWymaganaOpis
typestringnieURI encji Feature. Wymagany dla dołączenia, które tworzy wyłącznie encja Release. Musi być zgodny z typem w encji Aggregate, jeśli obie go deklarują.
descriptionstringnieOpcjonalna dokumentacja wyjaśniająca, dlaczego operator dołączył tę funkcję do połączenia.
infraobjectnieWymiarowanie operacyjne tego dołączenia, walidowane przez deklarację schematu encji Feature.

Dodatkowe właściwości są niedozwolone.

aggregate_routing

Kieruje wewnętrzne komponenty zagnieżdżonego podmodułu Aggregate do tej granicy. Odzwierciedla strukturę component/aggregate granicy na potrzeby kompozycji rekurencyjnej.

WłaściwośćTypWymaganaOpis
componentsmapa boundary_componentnieInstancje Component w zagnieżdżonym agregacie, które mają zostać skierowane do tej granicy. Kluczami są lokalne nazwy, które każdy komponent nosi wewnątrz tego podmodułu — ‘main-db’ dla komponentu, który mapa components samej granicy adresuje jako ‘data.main-db’ — ponieważ to jedyna nazwa, jaką ma on w tym miejscu. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
aggregatesmap of aggregate_routingnieKolejne agregaty zagnieżdżone w tym podagregacie (dla głęboko zagnieżdżonej kompozycji modułów). Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.

Dodatkowe właściwości są niedozwolone.

boundary

WłaściwośćTypWymaganaOpis
descriptionstringnieOpcjonalna dokumentacja opisująca przeznaczenie tej granicy i jej fizyczny cel (np. ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’).
directorystringnieFizyczna ścieżka wyjściowa dla generowania artefaktów GitOps. Obsługuje zmienne szablonów Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Łączona z subDirectory jako złączenie ścieżek w celu uzyskania ostatecznej ścieżki artefaktu.
subDirectorystringniePodścieżka na poziomie granicy dołączana do directory. Jeśli zostanie pominięta lub jest pusta zarówno w granicy, jak i w komponencie, domyślnie przyjmuje wartość ’{{ .capability }}’ na potrzeby automatycznego partycjonowania CI/CD; pusty ciąg wpisany tutaj jest traktowany jak pominięcie. Aby wyłączyć, należy ustawić ’.’ lub szablon, który daje w wyniku pusty ciąg.
syncWaveintegernieOpcjonalna fala wdrożenia dla granicy (liczba całkowita ze znakiem, domyślnie 0). Każdy komponent w tej granicy dziedziczy falę granicy do swojego węzła. Wartości ujemne są dozwolone (uruchamiane przed wszystkim innym); większe wartości uruchamiane są po mniejszych. W K8s i Helm to fala określa kolejność wdrożenia: staje się adnotacją argocd.argoproj.io/sync-wave, a na zasobie, który chart już oznacza jako hook Helm, staje się też wartością helm.sh/hook-weight tego hooka. W compose fala jest zarówno zapisywana jako etykieta usługi, jak i porządkuje usługi pliku, do którego jest renderowana, za pomocą depends_on między nimi — obejmuje więc każdą usługę w tym jednym pliku i nic poza nim. W cloudformation fala porządkuje provisioning stosu, do którego składana jest granica: każdy zasób w fali jest deklarowany jako zależny od zasobów poprzedniej fali, co ustala kolejność ich tworzenia i, w odwrotnej kolejności, usuwania. Dotyczy to wyłącznie kolejności tworzenia i usuwania — szablon stosu nie wyraża pojęcia gotowości zasobu, więc nic nie czeka, aż zasób stanie się zdatny do użytku. W terraform fala porządkuje bloki modułów konfiguracji głównej, do której składana jest granica: każdy moduł w fali jest deklarowany jako zależny od modułów poprzedniej fali, co ustala kolejność wykonywania akcji przez silnik. Dotyczy to wyłącznie kolejności akcji — konfiguracja nie wyraża pojęcia gotowości zasobu, więc nic nie czeka, aż zasób stanie się zdatny do użytku — a wartość jest również zapisywana w pochodzeniu kompilacji węzła. Kompilator przenosi tę samą wartość na każdy węzeł w granicy jako sync_wave tego węzła, gdzie zachowanie dla poszczególnych celów opisano ponownie od strony węzła. Zagnieżdżone granice nie dziedziczą jej niejawnie — każda deklaruje własną falę.
annotationsmapa string lub object lub nullnieAdnotacje Operator obejmujące całą granicę, kaskadowo przekazywane do zasobnika .context.annotations.release. Wartości to ciągi znaków, obiekty strukturalne lub null. Wartość strukturalna niesie konfigurację dla poszczególnych podkluczy, która jest głęboko scalana ze strukturalnymi rodzicami (dla każdego podklucza, wygrywa dziecko) i przechodzi przez sterowane adnotacjami rozwijanie encji Feature; w kontekście renderowania pojawiają się tylko wartości skalarne. Jawne null na kluczu odziedziczonym z granicy nadrzędnej usuwa odziedziczone powiązanie z efektywnego zestawu adnotacji tej granicy (sterowana adnotacjami rezygnacja z encji Feature), co przenosi się na każdy komponent kierowany do tej granicy, chyba że głębsze nadpisanie ponownie wprowadzi powiązanie.
featuresmapa objectnieFunkcje obejmujące całą granicę, stosowane do wszystkich zagnieżdżonych komponentów (np. domyślna siatka bezpieczeństwa). Blok uses funkcji jest rzutowany na każdy komponent w granicy, dzięki czemu wspólną zależność deklaruje się raz na poziomie granicy zamiast powtarzać ją w każdym komponencie. Klucze są nazwami instancji funkcji i mogą zawierać pełny URI typu funkcji (dozwolone kropki i ukośniki). Klucze: co najmniej jedna litera, cyfra, podkreślenie, kropka, ukośnik lub łącznik. Wzorzec: ^[a-zA-Z0-9_./-]+$.
boundariesmapa boundarynieZagnieżdżone granice logiczne (np. przestrzenie nazw w klastrze). Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka nie jest dozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.
componentsmapa boundary_componentnieKtóre komponenty z encji Aggregate są umieszczane w tej granicy. Klucze są nazwami instancji komponentów; komponent podagregatu adresuje się kwalifikowaną ścieżką z kropkami (np. ‘data.main-db’ — nazwa instancji agregatu, kropka, nazwa komponentu). Klucze: co najmniej jedna litera, cyfra, podkreślenie, kropka lub łącznik. Wzorzec: ^[a-zA-Z0-9_.-]+$.
aggregatesmap of aggregate_routingnieKieruje komponenty zagnieżdżonych podmodułów Aggregate do tej granicy. Klucze są nazwami instancji agregatów odpowiadającymi mapie spec.aggregates encji Aggregate. Jeśli zdefiniowano granice, każda instancja agregatu musi zostać umieszczona w dokładnie jednej granicy. Klucze: co najmniej jedna litera, cyfra, podkreślenie lub łącznik. Kropka nie jest dozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.

Dodatkowe właściwości są niedozwolone.

uses_block

Topologia strukturalna — należy do programisty. Deklaruje logiczne krawędzie sieciowe i zależności.

Klucze: co najmniej jedna litera, cyfra, podkreślnik lub łącznik. Kropka jest niedozwolona. Wzorzec: ^[a-zA-Z0-9_-]+$.

Wartości to string[] or map of object.

Żadne inne klucze nie są dozwolone.

inject_block

Agnostyczne trasowanie wstrzykiwania na połączeniu. Mapuje zmienne lokalne na klucze provides celu. Każdy mechanizm dostarczania (env, file, arg lub custom) jest zapisywany jako tablica wpisów {in, from} — z jawnym ‘from’ dla odwołań do provides. Mechanizm niestandardowy może mieć dowolną nazwę poza all: szablon odczytuje wszystkie mechanizmy scalone w jeden widok pod .context.inject.all, więc mechanizm o tej nazwie zostałby przez niego przesłonięty, a nadanie takiej nazwy zatrzymuje budowanie.

WłaściwośćTypWymaganaOpis
envinject_deliveryniePojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (identyfikator lokalny — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub klucz specyficzny dla niestandardowego mechanizmu) oraz dokładnie jedno z: ‘from’ (klucz provides do rozwiązania) lub ‘value’. W encji Release każdy wpis znajduje się na połączeniu, więc ‘from’ jest rozwiązywane względem provides celu, a wpis zawierający ‘value’ jest odrzucany.
fileinject_deliveryniePojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (identyfikator lokalny — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub klucz specyficzny dla niestandardowego mechanizmu) oraz dokładnie jedno z: ‘from’ (klucz provides do rozwiązania) lub ‘value’. W encji Release każdy wpis znajduje się na połączeniu, więc ‘from’ jest rozwiązywane względem provides celu, a wpis zawierający ‘value’ jest odrzucany.
arginject_deliveryniePojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (identyfikator lokalny — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub klucz specyficzny dla niestandardowego mechanizmu) oraz dokładnie jedno z: ‘from’ (klucz provides do rozwiązania) lub ‘value’. W encji Release każdy wpis znajduje się na połączeniu, więc ‘from’ jest rozwiązywane względem provides celu, a wpis zawierający ‘value’ jest odrzucany.

inject_delivery

Pojedynczy mechanizm dostarczania, zapisywany jako tablica wpisów. Każdy wpis zawiera ‘in’ (identyfikator lokalny — nazwę zmiennej środowiskowej, ścieżkę pliku, flagę argumentu lub klucz specyficzny dla niestandardowego mechanizmu) oraz dokładnie jedno z: ‘from’ (klucz provides do rozwiązania) lub ‘value’. W encji Release każdy wpis znajduje się na połączeniu, więc ‘from’ jest rozwiązywane względem provides celu, a wpis zawierający ‘value’ jest odrzucany.

Typ: object[]