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

aggrega pin

aggrega pin <entity-path> zapisuje w pliku entity.lock obok encji Recipe lub FeatureRecipe przypięcie treści dla każdego wejścia, które encja odczytuje spoza własnego dokumentu. Jest to krok autora encji: należy go uruchomić, zanim encja zostanie użyta lub opublikowana, i zatwierdzić zapisany przez niego plik blokady.

aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml

Co jest rejestrowane

Encja może zależeć od bajtów spoza własnego dokumentu, a blokada przechowuje po jednym przypięciu dla każdego z nich:

  • Zdalne source:, którego współrzędne zapisano w całości — bez szablonu w kind, url, chart, module_subdir, version ani ref. Krok pobiera je i rejestruje wersję, do której zostało rozwiązane — dla źródła git commit wskazany przez ref — oraz skrót treści tego, co pobrano.
  • Plik importowany przez wpis artifacts za pomocą $import. Krok oblicza skrót pliku w takiej postaci, w jakiej znajduje się w przestrzeni roboczej.
  • Każdy plik source:, które wskazuje katalog lub plik obok encji. Nic nie jest pobierane: krok oblicza skrót każdego pliku, który źródło wnosi do zawartości publikacji encji — każdego pliku w wskazanym katalogu, który zachowują reguły ignorowania encji, albo tego jednego pliku — i rejestruje go według ścieżki względem encji. Plik obok encji Recipe, którego źródło nie wnosi, na przykład README, nie jest przypinany. Źródło zapisane jako szablon, na przykład ./charts/{{ .values.flavour }}, wskazuje swój katalog dopiero wtedy, gdy wypełni go encja Release, dlatego wnosi każdy plik w katalogu encji, który zachowują reguły, i każdy z nich jest przypinany. Kompilacja porównuje źródło z tymi przypięciami, zanim odczyta je provider, więc plik dodany, zmieniony lub usunięty od czasu przypięcia zatrzymuje kompilację — A local source no longer matches the pins recorded beside its Recipe (Lokalne źródło nie odpowiada już przypięciom zarejestrowanym obok jego Recipe).
  • Same reguły ignorowania, dla source: będącego katalogiem. Krok rejestruje, który plugin obsłużył capability encji, oraz dokładne reguły, które złożył, zgodnie z opisem w następnej sekcji.

Czego krok nie rejestruje: zdalnego źródła, którego współrzędne są wypełniane z szablonu — wskazuje ono artefakt dopiero wtedy, gdy wypełni je encja Release, i jest przypinane w pliku lockfile każdej encji Release przez aggrega pull — oraz wpisu artifacts zapisanego inline lub pobranego z encji ArtifactLibrary. Sam plik jest opisany pole po polu w schemacie blokady encji.

Encja Release nie jest potrzebna. Źródło zapisane w całości wskazuje ten sam artefakt dla każdej encji Release, która kiedykolwiek użyje encji, więc jego rozwiązanie nie wymaga niczego, co dostarcza Release. Dzięki temu autor może przypiąć encję w przestrzeni roboczej, w której nie ma żadnej encji Release.

Plik encji nigdy nie jest zapisywany. To, co krok wyprowadza, trafia obok encji; to, co wpisano, pozostaje dokładnie w takiej postaci, w jakiej zostało wpisane. Ponowne uruchomienie na niezmienionych danych wejściowych pozostawia blokadę identyczną co do bajtu, a encja, która przestaje odczytywać cokolwiek rejestrowanego w blokadzie, traci swoją blokadę. Encja Component, Feature lub dowolnego innego rodzaju, która nie odczytuje takich danych wejściowych, jest zgłaszana jako niemająca nic do przypięcia, a niczego obok niej się nie zmienia.

Które pliki są dostarczane z encją

Encja Recipe lub FeatureRecipe, której source: wskazuje katalog obok niej — współlokowany chart, moduł — przy publikacji zawiera pliki tego katalogu. Nie każdy plik w nim tam należy: katalog systemu kontroli wersji, pamięć podręczna zależności, pozostałości edytora. O tym, które pliki należą, decydują reguły ignorowania w składni używanej przez .gitignore, a kontrola nad nimi należy do autora. Pochodzą one z dwóch miejsc:

  • Plugin renderujący capability encji deklaruje, czego jego własny ekosystem nigdy nie dostarcza. Pluginy chartów pomijają katalogi kontroli wersji (.git/, .hg/, .svn/, .bzr/) oraz ukryte pliki w templates/ chartu i respektują własny plik .helmignore chartu: wszędzie tam, gdzie przeglądanie źródła go napotka, jego wiersze są odczytywane jako dodatkowe reguły dla katalogu, który go zawiera. Plugin Terraform pomija katalogi kontroli wersji oraz katalog roboczy .terraform/ — ale nie plik blokady zależności, który ma podróżować razem z modułem — i w ten sam sposób respektuje .terraformignore. Plugin, który niczego nie deklaruje, pozostawia wszystko.
  • Własny plik .aggregaignore, jeden plik obok dokumentu encji, w tej samej składni. Jego wiersze obowiązują po regułach pluginu i po każdym pliku ignorowania wskazanym przez plugin, więc ostatnie słowo co do każdej wymienionej ścieżki należy do autora: wiersz taki jak .venv/ pomija katalog, o którym plugin nic nie wie, a wiersz taki jak !.git/ przywraca katalog pominięty przez plugin. Sam plik nigdy nie podróżuje; podróżują jego reguły, wewnątrz blokady.
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

Każda reguła jest odczytywana względem katalogu, do którego należy. Reguła zadeklarowana przez plugin jest odczytywana od korzenia katalogu źródłowego; wiersz pliku .helmignore — od katalogu zawierającego ten plik; wiersz pliku .aggregaignore — od własnego katalogu encji. Reguła bez ukośnika lub tylko z końcowym ukośnikiem pasuje do nazwy na dowolnej głębokości; końcowy ukośnik pasuje tylko do katalogu; początkowy ! przywraca to, co wcześniejsza reguła pominęła. Do katalogu pominiętego przez regułę nie następuje wejście, więc plik w jego wnętrzu wraca dopiero wtedy, gdy wraca sam katalog — samo !.git/HEAD nie przywraca pliku, dopóki .git/ jest pominięty, a !.git/ go przywraca.

Odczytywane są reguły tego pluginu, który w chwili przypinania obsługuje capability w obszarze roboczym: powiązania dostawcy z obszaru roboczego dla tej capability albo, w przeciwnym razie, pluginu wbudowanego w aggrega. Krok zapisuje w entity.lock ten plugin po nazwie, takiej jak provider/terraform, bez wersji, oraz dokładne reguły, które złożył; ponowne przypięcie przy nowszej wersji aggrega, której plugin deklaruje te same reguły, pozostawia blokadę bez zmian. Od tej chwili każde odczytanie katalogu stosuje zapisane reguły i żadne inne: publikacja encji, porównanie, któremu pull lub push poddaje blokadę, wiersz encji w pliku lockfile, porównanie podczas budowania, renderowanie przekazujące katalog dostawcy oraz aggrega pull --verify. Dzięki temu publikowane jest dokładnie to, co renderuje własne budowanie, a zmienione powiązanie, edytowany plik .aggregaignore czy nowsza wersja aggrega niczego nie zmieniają aż do ponownego przypięcia — wtedy diff blokady pokazuje, co się zmieniło. Plik, który plugin wskazuje jako plik ignorowania, taki jak .helmignore, sam jest jednym z plików źródła i jest przypinany jak każdy inny, chyba że pominie go reguła, więc jego edycja bez ponownego przypięcia zostanie wykryta przy następnym pull lub budowaniu. Blokada, która nie zapisuje żadnych reguł, zachowuje każdy plik w katalogu.

Konsument renderuje pliki zachowane przez reguły autora. Plugin może renderować encję Recipe opublikowaną dla jego capability, gdy posługuje się tą samą wersją ABI, jego kontrakt odpowiada deklaracji jego encji i nie potrzebuje żadnego pliku spoza opublikowanego zestawu. Plugin, który potrzebuje pliku pominiętego w zestawie, musi wyraźnie zakończyć budowanie błędem i wskazać ten plik; rolą hosta jest odmowa spakowania lub odczytu każdego pliku, którego zestaw nie zawiera, z jego wskazaniem. Jeśli plugin, który obszar roboczy konsumenta wiąże z daną capability, deklaruje inne reguły niż zapisane w blokadzie autora, aggrega pull u konsumenta zgłasza to w ostrzeżeniu wskazującym oba pluginy i różnicę, po czym kontynuuje.

Dowiązanie symboliczne wśród plików encji jest odrzucane, niezależnie od tego, dokąd prowadzi i czy daje się rozwiązać — zob. A symbolic link sits among the files an entity carries (Dowiązanie symboliczne znajduje się wśród plików, które zawiera encja). Dowiązanie pominięte przez reguły jest pomijane jak każdy inny pominięty plik. Ścieżka wskazana przez encję, która przechodzi przez katalog będący dowiązaniem prowadzącym poza katalog encji, również jest odrzucana, zanim cokolwiek zostanie przypięte — zob. A path names content outside the entity’s own directory (Ścieżka wskazuje zawartość spoza własnego katalogu encji).

Gdzie trafia blokada

Blokada jest zapisywana obok wskazanego dokumentu, w tym samym katalogu, więc encja potrzebuje miejsca z prawem zapisu: dokumentu w jednym z własnych katalogów. Encja, którą pull rozwiązał z pamięci podręcznej treści, nie ma takiego miejsca i nic jej nigdy nie przypina.

Jeden katalog, jedna encja. Katalog zawiera jeden plik entity.lock, więc krok odrzuca encję Recipe lub FeatureRecipe, która dzieli swój katalog z jakąkolwiek inną encją, niezależnie od tego, czy któraś z nich ma coś do przypięcia, i wymienia każdą przeszkadzającą encję — odmowa to An entity shares its directory with another entity (Encja dzieli swój katalog z inną encją). Każdy rodzaj ma własny katalog z wyjątkiem Aggregate, Release i Manifest, które mogą leżeć obok siebie; push stosuje tę samą zasadę do publikowanej encji, jak opisuje Jedna encja na katalog. Krok ocenia tylko to, dla czego zapisuje blokadę, więc encja Component lub encja dowolnego innego rodzaju, dla której nie ma nic do przypięcia, jest zgłaszana jako niemająca nic do przypięcia, a odmowa dosięga tej encji przy jej publikacji. Plik obok encji, który nie jest dokumentem encji — plik chartu, sam importowany plik — nie przeszkadza. Każdy dokument obok encji jest odczytywany wyłącznie z wnętrza obszaru roboczego lub, w przypadku dokumentu wskazanego poza nim, z wnętrza jego własnego katalogu — w którym przechowywana jest też blokada — więc dokument będący dowiązaniem prowadzącym na zewnątrz zatrzymuje krok, który wymienia to dowiązanie bez jego odczytywania, jak opisuje granica obszaru roboczego.

Kto przypina i kiedy

Przypinanie jest obowiązkiem autora. Encja, której wejścia nie są przypięte, nie jest jeszcze gotowa do użycia, dlatego domyślnie pull nie zapisuje żadnego przypięcia: dla encji Recipe lub FeatureRecipe w jednym z Twoich katalogów, którą buduje encja Release, porównuje to, co zapisałby ten krok, z zawartością blokady i zatrzymuje się, gdy brakuje przypięcia lub nie odpowiada ono już swojemu wejściu. Zatrzymanie wskazuje encję, każde wejście wraz z informacją, czy jest to źródło zdalne, importowany plik czy plik źródła lokalnego, oraz to polecenie. Jest to An entity reads an input the lock beside it records no pin for (Encja odczytuje wejście, dla którego blokada obok niej nie zapisuje przypięcia). Push poddaje publikowaną encję temu samemu porównaniu i odmawia z tym samym zatrzymaniem, więc encja nie może trafić do rejestru przez aggrega push z niezapisanym przypięciem — opisuje to Przypinanie przed publikacją. Źródło lokalne jest traktowane jako jeden zbiór plików: blokada, która nie zapisuje żadnego z nich, zatrzymuje pull lub push, podobnie jak plik dodany, zmieniony lub usunięty od czasu przypięcia, tak jak każde inne brakujące lub nieaktualne przypięcie.

Zatrzymanie przy pierwszym pull naprawia wydawca, nigdy odbiorca. Jeśli korzysta się z katalogu tworzonego przez kogoś innego — na przykład z jego kopii roboczej we własnym katalogu — a znajdująca się tam encja nie jest przypięta, autor nigdy nie uruchomił tego kroku. Rozwiązaniem nie jest ręczna edycja jego katalogu: należy ustawić opisany niżej klucz obszaru roboczego, aby operacje pull same zapisywały przypięcia.

Dwa polecenia uruchamiają ten sam krok w imieniu użytkownika i zapisują te same bajty:

  • aggrega pull --pin-sources uruchamia go dla encji budowanych przez encję Release, zamiast się zatrzymywać.
  • aggrega push --pin-sources uruchamia go dla encji przed jej spakowaniem, dzięki czemu zapisana blokada jest częścią publikowanej zawartości, zamiast odmawiać.

Każde z nich ma klucz obszaru roboczego, który czyni przypinanie domyślnym, pin_sources_at_pull i pin_sources_at_push; oba są domyślnie wyłączone i każdy dotyczy tylko własnego polecenia. Flaga nadpisuje swój klucz w obu kierunkach: --pin-sources przypina w jednym uruchomieniu niezależnie od wartości klucza, a --pin-sources=false nie przypina. Dzięki temu obszar roboczy skonfigurowany do przypinania może nadal przywrócić zatrzymanie dla jednego pull. Build, który wypełnia własny plik blokady, jest operacją pull, więc podlega pin_sources_at_pull. Klucze opisano w dokumentacji konfiguracji.

Zmiana opublikowanej encji

Dobra praktyka: zmiana w już opublikowanej encji należy do nowej wersji, po której następuje przypięcie — nigdy do ponownego przypięcia wersji, która już została wydana. Należy skopiować encję do katalogu nowej wersji, wprowadzić w nim zmianę i uruchomić aggrega pin na nowej wersji. Opublikowana wersja nadal opisuje dokładnie te bajty, z którymi została opublikowana, a konsument przechodzący na nową wersję robi to świadomie.

Produkt wymusza jedną połowę tej zasady: publikacja zmienionej treści w wersji, która jest już opublikowana, zostaje odrzucona, więc opublikowanej wersji nie można po cichu zastąpić. Drugiej połowy nie wymusza we własnym obszarze roboczym. Ponowne przypięcie istniejącej wersji po zmianie bywa czasem całkowicie słuszne — na przykład w przypadku encji konsumowanej wewnątrz jednej aplikacji i nieopublikowanej — więc nic tego nie blokuje, a przestrzeganie tej dyscypliny pozostaje w gestii użytkownika.

Ten sam krok w innych interfejsach

Demon udostępnia ten krok jako aggrega/pin (aggrega serve), a protokół narzędzi jako narzędzie pin (aggrega mcp); oba zapisują te same bajty, które zapisuje to polecenie. Przez nasłuch HTTP narzędzie zapisuje w obszarze roboczym i łączy się z hostami wskazanymi w źródłach encji, dlatego wywołujący potrzebuje zakresu workspace-write, aby je wywołać — tego samego uprawnienia, którego wymaga pull.

Zobacz także

Składnia

aggrega pin <entity-path> [flags]

Opis

Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input
the entity reads from outside its own document: a remote source: whose coordinates you wrote out
in full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before you
publish it, and after every change to one of its inputs — and commit the entity.lock it writes
beside the entity. A pull over an entity whose lock does not record these pins halts and names
this command, and so does a push of it; so does one whose local source has had a file added,
changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for every
Release that uses the entity, so it is resolved and pinned here, with nothing supplied. A remote
source whose coordinates are filled in from a template is not pinned here: which artifact it names is
decided by each Release, and each identity it resolves to is pinned in that Release's lockfile.
A source that names a directory beside the entity is not fetched: each file it contributes to what
a publication of the entity carries is digested as it stands and pinned by its path, so a build
refuses a file added, changed or removed after the pin. A local source written as a template
contributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads the
ignore rules the plugin serving the entity's capability declares — this workspace's provider binding
for that capability, or else the plugin built into aggrega — together with the ignore files that
plugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside the
entity, in gitignore syntax, whose lines come last and so have the final say. It records the plugin
and the composed rules in the entity.lock, and every publication, pull, build and render of the
entity applies the recorded rules and no others, so a changed binding or a newer binary moves
nothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name is
read from its own directory and the lock lands next to it. The entity file itself is never
written to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that reads
nothing a lock records has its lock removed. A Component, a Feature or any other kind that reads
no such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares its
directory with any other entity, naming the entity in the way, whether or not either has anything
to pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sit
side by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, and
write the same bytes.

Flagi

FlagaDomyślnieOpis
--dry-runfalseRozwiązuje dane wejściowe encji i wypisuje plik entity.lock, który krok by zapisał, zamiast go zapisywać: jego ścieżka i zawartość trafiają na stdout, a nic na dysku się nie zmienia. Blokada, którą krok pozostawiłby identyczną bajt po bajcie, nie jest wypisywana. Rozwiązywanie przebiega dokładnie tak samo jak w zwykłym trybie, więc pamięć podręczna treści nadal jest zapełniana