Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

aggrega pin

aggrega pin <entity-path> ghi lại, trong tệp entity.lock nằm cạnh một Recipe hoặc FeatureRecipe, mã ghim nội dung cho mọi đầu vào mà thực thể đọc từ bên ngoài tài liệu của chính nó. Đây là bước của tác giả thực thể: hãy chạy lệnh này trước khi thực thể được sử dụng hoặc xuất bản, và commit tệp khóa mà nó ghi ra.

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

Những gì nó ghi lại

Một thực thể có thể phụ thuộc vào các byte nằm ngoài tài liệu của chính nó, và tệp lock giữ một pin cho mỗi phụ thuộc đó:

  • Một source: từ xa mà bạn đã viết đầy đủ tọa độ — không có template trong kind, url, chart, module_subdir, version hay ref của nó. Bước này tải nó về và ghi lại phiên bản mà nó được phân giải thành — với một nguồn git, đó là commit mà ref của nó chỉ định — cùng digest nội dung của những gì đã tải về.
  • Một tệp mà một mục artifacts nhập bằng $import. Bước này tính digest của tệp đúng như nó đang có trong workspace của bạn.
  • Từng tệp của một source: chỉ định một thư mục hoặc một tệp nằm cạnh thực thể. Không có gì được tải về: bước này tính digest của từng tệp mà nguồn đóng góp vào những gì một bản phát hành của thực thể mang theo — mọi tệp trong thư mục nó chỉ định mà các quy tắc ignore của thực thể giữ lại, hoặc một tệp duy nhất đó — và ghi lại tệp đó theo đường dẫn của nó cạnh thực thể. Một tệp nằm cạnh Recipe mà nguồn không đóng góp, chẳng hạn README, sẽ không được pin. Một nguồn được viết dưới dạng template, chẳng hạn ./charts/{{ .values.flavour }}, chỉ chỉ định thư mục của nó khi một Release điền giá trị vào, nên nó đóng góp mọi tệp trong thư mục của thực thể mà các quy tắc giữ lại, và từng tệp đó đều được pin. Một bản build so sánh nguồn với các pin này trước khi provider của nó đọc nguồn, nên một tệp được thêm, thay đổi hoặc xóa kể từ lúc pin sẽ làm dừng bản build — A local source no longer matches the pins recorded beside its Recipe (Một nguồn cục bộ không còn khớp với các pin được ghi lại cạnh Recipe của nó).
  • Bản thân các quy tắc ignore, với một source: là thư mục. Bước này ghi lại plugin nào đã phục vụ capability của thực thể và chính xác các quy tắc mà nó đã tổng hợp, như phần tiếp theo mô tả.

Những gì nó không ghi lại: một nguồn từ xa có tọa độ được điền từ template, vốn chỉ chỉ định một artifact khi một Release điền giá trị vào và được pin trong lockfile của từng Release bởi aggrega pull; và một mục artifacts nội tuyến hoặc một mục lấy từ ArtifactLibrary. Bản thân tệp được mô tả theo từng trường trong schema của entity lock.

Không cần Release nào. Một nguồn được viết đầy đủ chỉ định cùng một artifact cho mọi Release từng sử dụng thực thể, nên việc phân giải nó không cần bất cứ thứ gì do một Release cung cấp. Đó là điều cho phép tác giả pin một thực thể trong một workspace hoàn toàn không có Release nào.

Tệp thực thể không bao giờ bị ghi. Những gì bước này suy ra được đặt cạnh thực thể; những gì bạn đã gõ được giữ nguyên đúng như bạn đã gõ. Chạy lại trên các đầu vào không thay đổi sẽ giữ tệp lock giống hệt từng byte, và một thực thể không còn đọc bất cứ thứ gì mà tệp lock ghi lại sẽ bị xóa tệp lock của nó. Một Component, một Feature, hoặc bất kỳ loại nào khác không đọc đầu vào như vậy sẽ được báo là không có gì để pin, và không có gì cạnh nó bị động đến.

Những tệp nào đi kèm một thực thể

Một Recipe hoặc FeatureRecipe có source: chỉ đến một thư mục bên cạnh nó — một chart đặt cùng chỗ, một module — sẽ mang theo các tệp của thư mục đó khi được xuất bản. Không phải tệp nào trong đó cũng thuộc về nơi ấy: một thư mục quản lý phiên bản, một bộ nhớ đệm phụ thuộc, các tệp sót lại của trình soạn thảo. Những tệp nào thuộc về được quyết định bởi các quy tắc bỏ qua, theo cú pháp mà .gitignore dùng, và bạn kiểm soát chúng. Chúng đến từ hai nơi:

  • Plugin kết xuất capability của thực thể khai báo những gì hệ sinh thái của chính nó không bao giờ đóng gói. Các plugin chart loại bỏ các thư mục quản lý phiên bản (.git/, .hg/, .svn/, .bzr/) và các tệp ẩn trong templates/ của chart, đồng thời tuân theo .helmignore riêng của chart: bất cứ nơi nào quá trình duyệt source gặp một tệp như vậy, các dòng của nó được đọc như các quy tắc bổ sung cho thư mục chứa nó. Plugin Terraform loại bỏ các thư mục quản lý phiên bản và thư mục làm việc .terraform/ — không phải tệp khóa phụ thuộc, vốn được thiết kế để đi cùng module — và tuân theo .terraformignore theo cùng cách. Một plugin không khai báo gì sẽ giữ lại mọi thứ.
  • Tệp .aggregaignore của riêng bạn, một tệp đặt bên cạnh tài liệu thực thể, cùng cú pháp. Các dòng của nó áp dụng sau các quy tắc của plugin và sau mọi tệp bỏ qua mà plugin chỉ định, nên bạn có tiếng nói cuối cùng với bất kỳ đường dẫn nào bạn nêu: một dòng như .venv/ loại bỏ một thư mục mà plugin không biết đến, và một dòng như !.git/ đưa trở lại một thư mục mà plugin đã loại bỏ. Bản thân tệp không bao giờ được mang theo; các quy tắc của nó thì có, bên trong lock.
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

Mỗi quy tắc được đọc tương đối với thư mục mà nó thuộc về. Một quy tắc do plugin khai báo được đọc từ gốc của thư mục source; một dòng của .helmignore từ thư mục chứa tệp đó; một dòng của .aggregaignore của bạn từ thư mục riêng của thực thể. Một quy tắc không có dấu gạch chéo, hoặc chỉ có dấu gạch chéo ở cuối, khớp với một tên ở bất kỳ độ sâu nào; dấu gạch chéo ở cuối chỉ khớp với thư mục; dấu ! ở đầu đưa trở lại những gì một quy tắc trước đó đã loại bỏ. Một thư mục bị quy tắc loại bỏ sẽ không được duyệt vào, nên một tệp bên trong nó chỉ quay lại khi chính thư mục đó quay lại — chỉ riêng !.git/HEAD không đưa tệp trở lại khi .git/ vẫn bị loại bỏ, còn !.git/ thì có.

Plugin có các quy tắc được đọc là plugin đang phục vụ capability trong workspace của bạn khi bạn pin: liên kết provider của workspace cho capability đó, hoặc nếu không thì plugin tích hợp sẵn trong aggrega. Bước này ghi lại plugin đó theo tên, chẳng hạn provider/terraform, không kèm phiên bản, cùng các quy tắc chính xác mà nó đã tổng hợp vào entity.lock; pin lại với một aggrega mới hơn có plugin khai báo cùng các quy tắc sẽ giữ nguyên lock. Từ đó trở đi, mọi lần đọc thư mục đều áp dụng các quy tắc đã ghi và không gì khác: một lần xuất bản thực thể, phép so sánh mà một lần pull hay push đối chiếu với lock, hàng của thực thể trong lockfile, phép so sánh của một bản build, lần kết xuất trao thư mục cho một provider, và aggrega pull --verify. Vì vậy những gì bạn xuất bản chính xác là những gì bản build của bạn kết xuất, và một liên kết đã thay đổi, một .aggregaignore đã chỉnh sửa hay một aggrega mới hơn không thay đổi gì cho đến khi bạn pin lại — lúc đó diff của lock cho thấy những gì đã thay đổi. Một tệp mà plugin chỉ định là tệp bỏ qua, chẳng hạn .helmignore, bản thân nó cũng là một trong các tệp của source và được pin như mọi tệp khác trừ khi một quy tắc loại bỏ nó, nên việc chỉnh sửa nó mà không pin lại sẽ bị phát hiện ở lần pull hoặc build tiếp theo. Một lock không ghi quy tắc nào sẽ giữ mọi tệp trong thư mục.

Bên sử dụng kết xuất các tệp mà quy tắc của bạn đã giữ lại. Một plugin có thể kết xuất một Recipe được xuất bản cho capability của nó khi nó dùng cùng phiên bản ABI, hợp đồng của nó khớp với khai báo của thực thể của nó, và nó không cần tệp nào ngoài tập đã xuất bản. Một plugin cần một tệp mà tập đó đã loại bỏ phải làm bản build thất bại một cách rõ ràng và nêu tên tệp; phần việc của host là từ chối mọi thao tác đóng gói hoặc đọc một tệp mà tập đó không mang theo, kèm tên tệp. Khi plugin mà workspace của bên sử dụng liên kết cho capability khai báo các quy tắc khác với những quy tắc lock của bạn ghi lại, aggrega pull của bên sử dụng sẽ báo điều đó trong một cảnh báo nêu tên cả hai plugin và điểm khác biệt, rồi tiếp tục.

Một liên kết tượng trưng nằm trong các tệp của thực thể sẽ bị từ chối, bất kể nó trỏ đến đâu và dù nó có phân giải được hay không — xem A symbolic link sits among the files an entity carries (Một liên kết tượng trưng nằm trong các tệp mà một thực thể mang theo). Một liên kết mà quy tắc của bạn loại bỏ sẽ được bỏ qua như mọi tệp khác bị loại bỏ. Một đường dẫn mà thực thể nêu ra đi qua một thư mục là liên kết dẫn ra ngoài thư mục của thực thể cũng bị từ chối, trước khi bất cứ thứ gì được pin — xem A path names content outside the entity’s own directory (Một đường dẫn chỉ đến nội dung bên ngoài thư mục riêng của thực thể).

Nơi đặt tệp khóa

Tệp khóa được ghi bên cạnh tài liệu mà bạn chỉ định, trong cùng thư mục, nên thực thể cần một nơi có thể ghi được: một tài liệu nằm trong một thư mục của bạn. Một thực thể mà lệnh pull phân giải từ bộ nhớ đệm nội dung không có nơi như vậy và không bao giờ được ghim bởi bất cứ thứ gì.

Một thư mục, một thực thể. Mỗi thư mục chứa một entity.lock, nên bước này từ chối một Recipe hoặc FeatureRecipe dùng chung thư mục với bất kỳ thực thể nào khác, dù thực thể nào trong số đó có gì để ghim hay không, và nêu tên từng thực thể gây cản trở — lỗi từ chối là An entity shares its directory with another entity (Một thực thể dùng chung thư mục với một thực thể khác). Mọi loại thực thể đều có thư mục riêng, trừ Aggregate, Release và Manifest, vốn có thể nằm cạnh nhau; lệnh push áp cùng quy tắc này cho thực thể mà nó xuất bản, như One entity per directory (Mỗi thư mục một thực thể) trình bày. Bước này chỉ xét những gì nó ghi tệp khóa cho, nên một Component hoặc bất kỳ loại nào khác mà nó không có gì để ghim sẽ được báo là không có gì để ghim, và lỗi từ chối sẽ đến với thực thể đó khi nó được xuất bản. Một tệp bên cạnh thực thể mà không phải là tài liệu thực thể — một tệp chart, chính tệp được nhập — không gây cản trở. Mỗi tài liệu bên cạnh thực thể chỉ được đọc từ bên trong workspace, hoặc, với một tài liệu bạn chỉ định nằm ngoài workspace, từ bên trong thư mục của chính nó — nơi tệp khóa cũng được lưu — nên một tài liệu là liên kết dẫn ra ngoài sẽ làm bước này dừng lại và nêu tên liên kết đó mà không đọc nó, như ranh giới workspace trình bày.

Ai ghim, và khi nào

Ghim là nghĩa vụ của người soạn thảo. Một entity có các đầu vào chưa được ghim thì chưa sẵn sàng để được sử dụng, nên theo mặc định một lần pull không ghi lại pin nào: với một Recipe hoặc FeatureRecipe nằm trong một thư mục catalog của bạn mà Release build, nó so sánh những gì bước này sẽ ghi lại với những gì lock đang giữ, và dừng lại khi một pin bị thiếu hoặc không còn khớp với đầu vào của nó. Lỗi dừng nêu tên entity, từng đầu vào và cho biết đó là một nguồn từ xa, một tệp được import hay một tệp của một nguồn cục bộ, cùng với lệnh này. Đó là An entity reads an input the lock beside it records no pin for (Một entity đọc một đầu vào mà lock bên cạnh nó không ghi pin nào). Một lần push áp dụng cùng phép so sánh đó cho entity mà nó xuất bản và từ chối với cùng lỗi dừng, nên một entity không thể đến được registry qua aggrega push khi còn một pin chưa được ghi lại — Ghim trước khi xuất bản trình bày điều đó. Một nguồn cục bộ được xem như một tập tệp duy nhất: một lock không ghi lại tệp nào trong số đó sẽ chặn một lần pull hoặc push, và một tệp được thêm, thay đổi hoặc xóa kể từ lúc ghim cũng vậy, giống như mọi pin bị thiếu hoặc lỗi thời khác.

Lỗi dừng ở lần pull đầu tiên là việc của người xuất bản phải sửa, không bao giờ là của người sử dụng. Khi bạn sử dụng một catalog do người khác soạn — chẳng hạn một bản checkout của nó trong một thư mục của riêng bạn — và một entity trong đó chưa được ghim, thì tác giả chưa bao giờ chạy bước này. Cách khắc phục của bạn không phải là sửa thủ công thư mục của họ: hãy đặt khóa workspace dưới đây, để các lần pull của bạn tự ghi lại các pin.

Hai lệnh chạy chính bước này thay cho bạn, và ghi ra cùng các byte:

  • aggrega pull --pin-sources chạy nó trên các entity mà Release build, thay vì dừng lại.
  • aggrega push --pin-sources chạy nó trên entity trước khi đóng gói, để lock mà nó ghi ra trở thành một phần của những gì được xuất bản, thay vì từ chối.

Mỗi lệnh có một khóa workspace làm cho việc ghim trở thành mặc định của nó, pin_sources_at_pull và pin_sources_at_push, cả hai đều tắt theo mặc định và mỗi khóa chỉ chi phối lệnh của riêng nó. Cờ ghi đè khóa của nó theo cả hai chiều: --pin-sources ghim cho một lần chạy bất kể khóa nói gì, còn --pin-sources=false thì không ghim. Vì vậy một workspace được cấu hình để ghim vẫn có thể lấy lại lỗi dừng cho một lần pull. Một lần build tự điền lockfile của nó là một lần pull, nên nó tuân theo pin_sources_at_pull. Các khóa được mô tả trong tài liệu tham khảo cấu hình.

Thay đổi một entity đã phát hành

Thực hành tốt nhất: một chỉnh sửa đối với entity bạn đã phát hành thuộc về một phiên bản mới, rồi đến một lần pin — không bao giờ pin lại phiên bản đã được phát hành. Sao chép entity vào một thư mục phiên bản mới, thực hiện thay đổi ở đó, rồi chạy aggrega pin trên phiên bản mới. Phiên bản đã phát hành tiếp tục mô tả chính xác những byte mà nó được phát hành cùng, và một bên sử dụng chuyển sang phiên bản mới là chuyển có chủ đích.

Sản phẩm thực thi một nửa của điều này: việc phát hành nội dung đã thay đổi ở một phiên bản đã được phát hành sẽ bị từ chối, nên một phiên bản đã phát hành không thể bị thay thế một cách âm thầm. Sản phẩm không thực thi nửa còn lại trong workspace của riêng bạn. Việc pin lại một phiên bản hiện có sau khi chỉnh sửa đôi khi hoàn toàn đúng — chẳng hạn một entity bạn sử dụng bên trong một ứng dụng và chưa phát hành — nên không có gì ngăn bạn, và việc giữ kỷ luật này là của bạn.

Cùng bước này trên các giao diện khác

Daemon cung cấp bước này dưới dạng aggrega/pin (aggrega serve), và giao thức công cụ cung cấp nó dưới dạng công cụ pin (aggrega mcp); cả hai đều ghi ra đúng những byte mà lệnh này ghi. Qua một HTTP listener, công cụ ghi bên trong workspace và truy cập tới các host mà nguồn của một entity chỉ định, vì vậy bên gọi cần phạm vi workspace-write để gọi nó — cùng quyền mà một lần pull cần.

Xem thêm

  • aggrega-pull.md — khóa của thực thể, những gì một lần build so sánh với nó, và việc dừng.
  • aggrega-push.md — phát hành một thực thể, và phát hành một phiên bản chỉ một lần.
  • configuration.md — pin_sources_at_pull và pin_sources_at_push.

Cú pháp

aggrega pin <entity-path> [flags]

Mô tả

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.

Cờ

CờMặc địnhMô tả
--dry-runfalsePhân giải các đầu vào của thực thể và in ra entity.lock mà bước này sẽ ghi, thay vì ghi nó: đường dẫn và nội dung mà nó sẽ chứa được đưa ra stdout, và không có gì trên đĩa thay đổi. Một khóa mà bước này sẽ để nguyên giống hệt từng byte thì không được in ra. Việc phân giải chạy đúng như khi không dùng cờ này, nên bộ nhớ đệm nội dung vẫn được điền