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

Przykłady do uruchomienia

Na początek Pierwsze kroki instalują Aggrega i prowadzą krok po kroku przez dwa z tych przykładów.

Kompletne przestrzenie robocze, które można sforkować i skompilować za pomocą CLI aggrega. Każda z nich to samodzielny katalog — encja Aggregate napisana przez dewelopera oraz jedna lub więcej par Release/Manifest — który buduje się bez żadnej konfiguracji poza tą, którą wymienia jego strona. Aby znaleźć przykład według wdrażanego produktu lub tego, co pokazuje, należy skorzystać ze strony Przykłady według produktu i możliwości, która wymienia każdy przykład z tego miejsca.

Przykłady występują w dwóch trybach — to dwa końce jednego programu nauki:

  • Korzystanie — przestrzeń robocza odwołuje się do encji katalogu biblioteki standardowej i lokalnie tworzy tylko własną treść służącą nauce. Buduje się bez flagi --catalog:

    Terminal window
    aggrega build --release release.yaml

    To, skąd odczytywane są te encje, zależy od przestrzeni roboczej. Katalog catalog/ w katalogu głównym przestrzeni roboczej jest odczytywany niezależnie od tego, czy cokolwiek go wskazuje, więc przestrzeń robocza tworząca własną treść do nauki może po prostu trzymać ją tam. Przestrzeń robocza zawierająca plik .aggrega-config.yaml odczytuje również każdy katalog wymieniony w catalog_dirs, a każdy z nich jest katalogiem, w którym trzyma encje. Wymienione katalogi są przeszukiwane najpierw, a catalog/ na końcu, a stos działa według zasady „pierwszy wygrywa”, więc encja we wcześniej przeszukiwanym katalogu przesłania encję o tej samej tożsamości w późniejszym. To, czego nie deklaruje żaden katalog lokalny — encje biblioteki standardowej — jest rozwiązywane z rejestru, który konfiguracja wskazuje jako default_registry, czyli hub.aggrega.ai. Przestrzeń robocza, która niczego nie tworzy lokalnie, nie potrzebuje lokalnego wpisu, a taka, która nie ma ani katalogu catalog/, ani pliku .aggrega-config.yaml, rozwiązuje wszystko przez skonfigurowany rejestr. Zapisanie catalog_dirs jako pustej listy oznacza, że przestrzeń robocza nie ma w ogóle lokalnego katalogu. Każda ścieżka w catalog_dirs wskazuje katalog wewnątrz przestrzeni roboczej, więc kopia całej przestrzeni roboczej umieszczona gdzie indziej buduje się bez zmian.

    Przestrzeń robocza z wieloma celami, która przechowuje osobny katalog encji dla każdego celu, wymienia katalogi każdego celu pod workspace.releases, z kluczem w postaci pliku encji Release, dzięki czemu każda encja Release jest budowana względem własnego katalogu encji.

  • Tworzenie — przestrzeń robocza buduje encje katalogu (Components, Features, Recipes) od zera w lokalnych katalogach catalog-*/. mariadb-adminer to opracowany przykład tworzenia; budowane w nim encje są tego samego rodzaju, co encje wykorzystywane w przykładach korzystania.

W jednym uruchomieniu buduje się jedno wydanie poleceniem aggrega build --release <release file>; strona każdego przykładu podaje jego własne polecenia. Obszar roboczy dostarcza swój katalog w sposób opisany powyżej; dla katalogu, którego obszar roboczy nie wskazuje, należy samodzielnie przekazać --catalog, jak pokazują strony, które tego wymagają.

Pliki blokad są generowane, a nie dostarczane, więc świeży klon nie ma żadnego, a pierwsze budowanie go potrzebuje. aggrega build domyślnie działa tylko do odczytu: bez pliku blokady zatrzymuje się i wskazuje dwie drogi dalej. Przy tym pierwszym budowaniu należy przekazać --auto-pull — aggrega build --release release.yaml --auto-pull — aby rozwiązać plik blokady podczas budowania; jednorazowe uruchomienie aggrega pull --release <release file> wcześniej daje ten sam efekt i pozwala wszystkim kolejnym budowaniom działać bez flagi.

W kopii roboczej repozytorium dokumentacji większość obszarów roboczych zawiera także skrypt pomocniczy build-release.sh, przez który budują własne testy repozytorium. Uruchamia on aggrega build dla jednego wydania, najpierw wypisując polecenie, i zgłasza, którego pliku binarnego aggrega użył i skąd ten plik pochodzi; aby wybrać plik binarny, należy ustawić AGGREGA_BIN. Kopia zapisana przez aggrega scaffold --example zawiera skrypt pomocniczy, ale bez wspólnego skryptu, który on wywołuje, więc taką kopię należy budować bezpośrednio poleceniem aggrega build.

Gdy przykład z tej strony wymienia kopię roboczą katalogu biblioteki standardowej, Import podaje, skąd ją pobrać.

Uzupełniają one strony koncepcyjne opisane w Przeglądzie przykładów: strona koncepcyjna wyjaśnia jedną ideę i odsyła do przestrzeni roboczej, która ją pokazuje; przestrzenie robocze tutaj to całe stosy, które można zbudować, przeczytać i dostosować.

Tam, gdzie strona pokazuje, co wytworzyło budowanie, blok ten jest skopiowany z rzeczywistego uruchomienia, aby można było porównać z nim własny wynik — a wszelkie pominięte wiersze są oznaczone. Czytanie wyników na tych stronach opisuje tę konwencję i używane oznaczenie.

Nie każdy katalog w tym miejscu jest pojedynczą przestrzenią roboczą. Przykłady quickstart zawierają po jednej przestrzeni roboczej na każdy krok, a przykłady importu po jednej na każdy etap importu, jak opisuje następny akapit. Jeden katalog nie zawiera żadnej przestrzeni roboczej: policy-in-ci zawiera dwa skrypty reguł, które odczytują katalog wyjściowy budowania i odrzucają go, gdy narusza regułę, wraz z krokiem potoku dla każdego z nich. Działają na wynikach przestrzeni roboczych w tym miejscu, a także na własnych.

Każdy przykład import-* — wymieniony pod możliwością import w Przykłady według produktu i możliwości — przechowuje projekt zapisany w innym formacie w takiej postaci, w jakiej zastaje go aggrega import, w dwóch folderach: source/, projekt, .aggrega-config.yaml, który czyni z niego przestrzeń roboczą, oraz plik odpowiedzi, z którego import odczytuje wartości, jakich nie może zawierać żadne źródło; oraz draft/, pliki zapisane przez import, bez zmian, przestrzeń robocza, którą da się zbudować w zapisanej postaci, wraz z tym, co import wypisał na standardowe wyjście (stdout.txt) i standardowe wyjście błędów (import.txt). Opis krok po kroku w Import omawia każdy etap. Jego check.sh uruchamia wspólny skrypt scripts/check-import-example.sh tego repozytorium, który ponownie importuje, porównuje to, co zapisuje i wypisuje, z draft/, a bloki cytowane w opisie z plikami przykładu, po czym waliduje i buduje przygotowaną encję Release.

Kolejność nauki

Każdy przykład tutaj zajmuje jedno miejsce w jednej kolejności nauki, wyznaczone przez tier i position w jego nagłówku: poziom po poziomie, w kolejności podanej na liście poziomów, a w obrębie każdego poziomu od najprostszego. W kolejności nauki wymienia w ten sposób każdy przykład, a sekcja Przykłady na pasku bocznym zachowuje tę samą kolejność. Poziomy można czytać od góry do dołu albo przejść od razu do tego, który odpowiada temu, co się robi; aby zamiast tego znaleźć przykład według tego, co wdraża lub co pokazuje, ta sama strona wymienia przykłady według produktu i według możliwości.

Build może też uruchamiać wtyczki na tym, co renderuje — zob. Kiedy sięgnąć po krok potoku.

Nagłówek każdego przykładu

README każdego przykładu zaczyna się krótkim nagłówkiem, zapisanym jako front matter YAML, który mówi, czym jest przykład: jaki ma poziom, jakie miejsce zajmuje w kolejności nauki, jakie produkty wdraża i co pokazuje. Strona Przykłady według produktu i możliwości jest generowana z tych nagłówków.

---
example:
level: start
tier: catalog-only
position: 1
products: [core/datastore/mariadb, core/devtool/adminer]
shows: [connections, credentials]
---

level to jeden z tych poziomów:

  • start — poziom „Tylko katalog”: złożony z encji katalogu, bez niczego napisanego poza encjami Aggregate, Manifest i Release.
  • authoring — poziom „Tworzenie”: tworzy encję Component, Feature lub Recipe albo pokazuje, jak jest zbudowana.
  • advanced — poziom „Zaawansowane”: granice, polityka zarządcza, encje Features sterowane adnotacjami oraz złożone stosy chmurowe.

tier to część kolejności nauki, do której należy przykład, jedna z tych grup, omawianych w tej kolejności:

  • start-here — Zacznij tutaj: dwa przykłady, które przewodnik „Pierwsze kroki” rozbudowuje krok po kroku, a potem dwa przykłady startowe dla chmury.
  • catalog-only — Tylko katalog: złożony z encji katalogu, bez niczego napisanego poza encjami Aggregate, Manifest i Release.
  • authoring — Tworzenie: pisze własną encję Component, Feature lub Recipe albo pokazuje, jak taka encja jest zbudowana.
  • advanced — Zaawansowane: granice, polityki zarządzania, Features sterowane adnotacjami i złożone stosy chmurowe, kilka z nich połączonych w jednym buildzie.
  • importers — Importery: projekt napisany w innym formacie, przekształcony przez aggrega import w szkice plików Aggrega, a następnie przejrzany i zbudowany.

position to miejsce przykładu w jego grupie, dodatnia liczba całkowita, której nie zajmuje żaden inny przykład tej grupy; grupa wymienia swoje przykłady od najniższej pozycji w górę, od najprostszego.

products wymienia każdą encję Component z katalogu wdrażaną przez przykład, według nazwy, którą nosi jej wpis w katalogu. Ogólny komponent obliczeniowy (na przykład core/compute/server) i encja zadeklarowana przez przykład na własny użytek nie są wymieniane, więc przykład może nie wymieniać żadnej.

shows wymienia to, co demonstruje przykład; każdy wpis pochodzi z tej listy:

  • multi-target — jedna encja Aggregate budowana dla dwóch lub więcej celów albo realizowana na dwa lub więcej sposobów.
  • recipe-selection — Manifest wybiera, która encja Recipe realizuje komponent lub która encja FeatureRecipe realizuje załącznik: według typu, instancji lub celu.
  • modules — encja Aggregate z katalogu zaimportowana jako moduł.
  • connections — komponenty połączone przez gniazda uses, z wartościami przekazywanymi przez każdą krawędź.
  • credentials — załączniki poświadczeń i sposób, w jaki każdy cel je dostarcza.
  • parameters — wartości wyniesione do parametrów, które wypełnia encja Release.
  • features — encje Features dołączone w innym celu niż poświadczenie, na przykład routing, monitorowanie, budżet, cache lub maskowanie.
  • boundaries — komponenty lub moduły umieszczone w granicach oraz to, co przechodzi między nimi.
  • policy — polityka zarządcza, która akceptuje lub odrzuca build, w trakcie budowania lub na podstawie jego wyjścia.
  • guardrails — encja Release, która ma się zatrzymać, oraz komunikat, z którym się zatrzymuje.
  • catalog-authoring — encja Component, Feature lub Recipe napisana dla przykładu, przechowywana obok niego lub opublikowana w katalogu.
  • cloud-infrastructure — wyjście Terraform lub CloudFormation dla zarządzanych usług chmurowych.
  • external-sources — encja Recipe, która pobiera to, co renderuje: chart nadrzędny, repozytorium git lub moduł.
  • import — projekt napisany w innym formacie, przekształcony przez aggrega import w szkice plików Aggrega, a następnie przejrzany i skompilowany.

Przykład wymienia co najmniej jeden produkt lub jedną możliwość, aby indeks mógł go umieścić. Jego README zawiera też sekcję ## Scaffold the example z poleceniem aggrega scaffold --example <name> w pierwszym bloku poleceń i cd <name> w drugim, bezpośrednio po której następuje sekcja ## Build, której pierwszy blok poleceń to to, co aggrega scaffold --example wypisuje jako następny krok do uruchomienia po tym cd. scripts/gen-examples-index.sh --check, uruchamiany z katalogu głównego tego repozytorium, sprawdza każdy nagłówek względem tych list, odrzuca przykład, w którym brakuje którejkolwiek z tych sekcji, oraz taki, który nie ma ani wykonywalnego check.sh, ani build-release.sh, i potwierdza, że indeks jest aktualny; aby ponownie zapisać indeks, należy go uruchomić bez --check.