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ść | Typ | Wymagana | Opis |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | tak | Stała: "aggrega.ai/v1beta1" |
kind | const “Release” | tak | Stała: "Release" |
metadata | object | tak | |
spec | object | tak | 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. |
Dodatkowe właściwości są niedozwolone.
release.metadata
| Właściwość | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | Co najmniej 1 znak. |
environment | string | tak | |
version | string | tak | Wersja 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-]+)*))?$. |
description | string | nie | Czym 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. |
maintainers | object[] | nie | Lista opiekunów, do których należy ta encja. |
license | string | nie | Identyfikator SPDX licencji oprogramowania opisywanego przez tę encję, np. MIT lub AGPL-3.0. Określa warunki tego oprogramowania, a nie warunki tego pliku. |
repository | string | nie | URL repozytorium Git, w którym znajdują się pliki źródłowe. |
home | string | nie | URL strony domowej, wiki lub dokumentacji tej encji. |
keywords | string[] | nie | Lista 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
name | string | tak | |
email | string | nie | |
url | string | nie |
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ść | Typ | Wymagana | Opis |
|---|---|---|---|
aggregate | string | nie | Odwoł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). |
manifest | string | nie | Odwoł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. |
extends | string | nie | Odwoł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. |
parameters | object | nie | Zależ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). |
boundaries | mapa boundary | nie | Głó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_-]+$. |
components | mapa boundary_component | nie | Instancje 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
description | string | nie | Opcjonalna dokumentacja opisująca rolę tego komponentu w tej granicy encji Release. |
subDirectory | string | nie | Nadpisanie 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. |
annotations | mapa string lub object lub null | nie | Adnotacje 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. |
infra | object | nie | Fizyczne wymiarowanie ściśle lokalne dla tego komponentu (np. repliki, IOPS dysku). |
features | mapa object | nie | Encje 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_./-]+$. |
uses | release_uses_block | nie | Powierzchnia 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
type | string | nie | URI 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ą. |
description | string | nie | Opcjonalna dokumentacja wyjaśniająca, dlaczego operator dołączył tę funkcję do połączenia. |
infra | object | nie | Wymiarowanie 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
components | mapa boundary_component | nie | Instancje 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_-]+$. |
aggregates | map of aggregate_routing | nie | Kolejne 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
description | string | nie | Opcjonalna dokumentacja opisująca przeznaczenie tej granicy i jej fizyczny cel (np. ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’). |
directory | string | nie | Fizyczna ś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. |
subDirectory | string | nie | Podś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. |
syncWave | integer | nie | Opcjonalna 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ę. |
annotations | mapa string lub object lub null | nie | Adnotacje 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. |
features | mapa object | nie | Funkcje 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_./-]+$. |
boundaries | mapa boundary | nie | Zagnież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_-]+$. |
components | mapa boundary_component | nie | Któ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_.-]+$. |
aggregates | map of aggregate_routing | nie | Kieruje 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ść | Typ | Wymagana | Opis |
|---|---|---|---|
env | inject_delivery | nie | 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. |
file | inject_delivery | nie | 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. |
arg | inject_delivery | nie | 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. |
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[]