aggrega build
aggrega build biên dịch một cặp Aggregate + Release thành các artifact gốc của provider (Helm manifest, Helm chart có thể phân phối lại, YAML docker-compose) trong dist/ tại thư mục gốc của workspace, như phần Đầu ra trình bày. Release là điểm vào duy nhất: nó chỉ định Aggregate và Manifest, khai báo các ranh giới, và định tuyến các component đến các provider.
Các cờ thông dụng
Hai cờ mang hành vi mà phần tham chiếu cờ bên dưới không thể tự diễn đạt hết:
--catalog <dir>— một thư mục chứa các thực thể catalog — các loại thực thể soạn thảo Component, Feature, Recipe và FeatureRecipe cùng với các loại thư viện, Aggregates và Plugins — được nạp đệ quy. Mỗi thư mục--catalogđược tìm kiếm trước các thư mục đã cấu hình, theo thứ tự được truyền vào. Để tìm kiếm một catalog cục bộ của dự án cùng với một catalog dùng chung, hãy truyền cả hai (--catalog ./catalog --catalog ../shared-catalog) hoặc liệt kê chúng trongcatalog_dirs. Với--detail, mọi thực thể bị một thư mục có độ ưu tiên cao hơn che khuất đều được báo cáo trên stderr, cùng với các cảnh báo build khác. Một thư mục--catalogkhông tồn tại sẽ dừng build và nêu tên thư mục đó. Một thư mục được liệt kê trongcatalog_dirsnhưng thực ra không phải là thư mục cũng vậy: build dừng trước khi bất cứ thứ gì được đọc hoặc ghi, và nêu tên mục đó cùng với tệp cấu hình và dòng liệt kê nó — xem Nơi đọc các thực thể cục bộ. Một bản build dừng lại vì một tham chiếu không phân giải được thành gì sẽ nêu tên, trong ghi chú bên dưới thông báo dừng, mỗi tệp trong các thư mục đó có khai báo một apiVersion của Aggrega — một dòng bắt đầu, không thụt lề, bằngapiVersion:với một giá trị bắt đầu bằngaggrega.ai/— mà không nạp được, chẳng hạn một tệp không phân tích được dưới dạng YAML, kèm lý do của chính trình phân tích cú pháp, trong số các tệp catalog bị bỏ qua khi nạp; một tệp YAML khai báo một apiVersion khác, hoặc không khai báo gì, không phải là tài liệu Aggrega và không bao giờ được nêu tên ở đó.--detail— báo cáo những gì bước pull đã làm, cùng chẩn đoán sự kiện pull tạm thời màaggrega pull --detailphát ra. Điều quyết định có gì để báo cáo hay không là liệu bước pull có được yêu cầu hay không — bằng--auto-pull, hoặc bằng cách bậtauto_pull— chứ không phải liệu lockfile đã có sẵn hay chưa: một bước pull được yêu cầu luôn chạy trong cả hai trường hợp, điền lockfile còn thiếu và tuân theo các pin trong lockfile đã có. Khi không có bước pull nào chạy, cờ này in một ghi chú một dòng ra stdout rồi tiếp tục — nó không bao giờ bịa ra một tầng phân giải mà lockfile đã commit không có. Để xem trạng thái phân giải sau pull của các phụ thuộc của một Release, hãy dùngaggrega inspect.
--dry-run được trình bày trong Xem trước một build mà không ghi ra, còn --trace và --trace-unredacted trong Đầu ra trace và Hiển thị các giá trị bị ẩn bên dưới.
Điền lockfile như một phần của quá trình build
Theo mặc định, build chỉ đọc đối với các phụ thuộc: nó cần một lockfile và không ghi lockfile nào. --auto-pull, cùng thiết lập workspace auto_pull, thêm bước pull vào build, nhờ đó một lệnh duy nhất vừa phân giải các phụ thuộc của Release vừa biên dịch dựa trên những gì nó đã phân giải.
Một chỉnh sửa đối với Release là điều lockfile nhận ra. Lockfile ghi lại Release — và mỗi Release mà nó mở rộng — theo digest của nội dung, nên một build chỉ đọc trên một Release đã được chỉnh sửa kể từ lần pull sẽ dừng lại trước khi bất cứ thứ gì được render, nêu tên tệp và yêu cầu bạn chạy aggrega pull --release <release>, lệnh này ghi lại chỉnh sửa trong khi vẫn tôn trọng mọi pin khác. Một thay đổi về chú thích hay khoảng trắng cũng được tính, vì digest bao phủ các byte đúng như chúng là. Một build tự động pull sẽ tự chạy bước pull đó, nên nó ghi lại chỉnh sửa và build.
Release được render một lần. Việc một Release tiêu thụ những đầu vào bên ngoài nào được suy ra từ việc render nó chứ không từ bất cứ điều gì các tài liệu của nó khai báo, nên bước pull render Release để tìm ra — và lần render đó chính là của build. Do đó một build tự động pull chỉ tốn một lần render, giống như một build thông thường trên một lockfile đã có sẵn.
Các cờ định hình một lần render được áp dụng cho nó. --trace, --verify-determinism, --disable-plugin-cache và --no-unsupported-field-warnings tác động đến lần render mà một build tự động pull thực hiện theo cùng cách chúng tác động đến một build thông thường, nên yêu cầu một trace hay một kiểm tra tính tất định trên một build một lệnh sẽ cho bạn đúng điều đó. --dry-run là ngoại lệ, và đó là một sự từ chối chứ không phải im lặng: một lần chạy thử không ghi gì trong khi bước pull có ghi, nên việc kết hợp hai thứ sẽ dừng lại trước khi làm bất kỳ việc gì (xem Xem trước một build mà không ghi nó).
Cách một bản build đọc những gì lockfile ghim
Một pin trong lockfile chỉ định nội dung — một digest — chứ không phải một vị trí. Với một thực thể, đó là digest của những gì một bản phát hành của nó mang theo, gồm tài liệu của nó và các tệp mà nó nêu tên, nên một bản sao của thực thể trong thư mục catalog và một mục cache chứa bản phát hành của nó mang cùng một pin, như Lockfile mô tả. Một bản build đọc từng phụ thuộc đã ghim từ các nguồn đã có sẵn trên máy: trước tiên là các thư mục catalog, như ở mọi nơi khác, sau đó là cache nội dung dưới .aggrega/cache. Việc đọc chúng không truy vấn registry nào; chỉ bước pull, ở nơi bản build chạy bước này, mới tải về.
Một mục cache không còn khớp với pin của nó sẽ bị bỏ qua. Một thực thể được sửa tại chỗ — một nội dung mới dưới cùng version — khiến cache nội dung vẫn giữ nội dung cũ dưới tên và phiên bản đó. Ở nơi một thư mục catalog chứa một bản sao có digest nội dung khớp với pin, bản build đọc bản sao đó và không bao giờ đọc mục cache, đồng thời thông báo điều này trên standard error, nêu tên mục cache và cả hai digest:
reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytesỞ nơi không có thư mục catalog nào chứa thực thể, một mục cache đầy đủ chứa đúng các byte đã ghim sẽ được đọc làm phụ thuộc, nên một thực thể bị xóa khỏi thư mục catalog của nó sau khi bản sao đã phát hành được tải về vẫn build được từ bản sao đó.
Ở nơi không có nguồn nào chứa các byte đã ghim, bản build dừng lại trước khi bất cứ thứ gì được render, với E0135 — hoặc E0133 ở nơi manifest của mục cache không phải là manifest mà lockfile ghim. Thông báo dừng nêu pin, mục cache và digest mà mục đó chứa, cùng từng bản sao của thực thể trong thư mục catalog kèm digest của nó, hoặc cho biết không có thư mục catalog nào chứa thực thể. Cách khắc phục là chạy pull khi có thể truy cập registry; lệnh này tải lại phiên bản đã ghim và đối chiếu những gì nó tải về với pin; xem Tuân theo và cập nhật để biết pull làm gì khi registry không còn phục vụ các byte đó.
Lần render mà aggrega pull chạy để phát hiện các đầu vào bên ngoài, cùng một bản build hoặc bản xem trước qua aggrega serve hoặc aggrega mcp, đều đọc các pin của chúng theo cùng cách này.
Đầu vào bên ngoài tại thời điểm build
Một lần render có thể yêu cầu nội dung từ một URL từ xa — ví dụ, schema values của một chart có tham chiếu từ xa — và một lần build không bao giờ tải nội dung đó về để thêm vào những gì lần render được phép đọc. Yêu cầu đến một URL mà lockfile đã ghim được phục vụ từ kho đầu vào của workspace và được xác minh với digest đã ghi lại trước khi bất kỳ byte nào đến được lần render. Yêu cầu đến một URL chưa được ghim sẽ dừng lại, nêu tên URL và bước ghim nó; không có thiết lập nào biến việc dừng đó thành một lần tải, vì âm thầm mở rộng tập đầu vào mà một lần build đọc chính là điều mà một bản build có thể tái lập không được làm.
Khi bản sao của một đầu vào đã ghim trong kho bị mất, riêng đầu vào đó được tải lại theo digest mà lockfile đã ghi và được kiểm tra với digest đó trước khi bất cứ thứ gì được ghi ra hoặc trả về. Việc này không thể thay đổi những gì lần render thấy — digest đã được cam kết khi đầu vào được ghim — nên nó sửa chữa kho chứ không thêm vào bao đóng, và lockfile được giữ nguyên từng byte. Ở chế độ offline thì ngay cả việc đó cũng không có phương tiện truyền tải, và bản sao bị thiếu sẽ khiến quá trình dừng lại, nêu tên chế độ đó.
Việc ghim diễn ra khi các phụ thuộc của Release được phân giải, nên những gì một lần build được phép đọc đã được xác định trước khi build bắt đầu. aggrega pull là bước đó, và là bước duy nhất.
Bản ghi tin cậy plugin
Một số hành vi của một bản build phụ thuộc vào plugins-trust.yaml, tệp được commit nằm cạnh lockfile của Release, ghi lại plugin mà mỗi attachment trả về phán quyết đã được phân giải tới — một attachment plugins.governance ở vai trò ir-verdict hoặc render-verdict, và mọi attachment plugins.linter. aggrega pull ghi tệp này và schema của bản ghi tin cậy plugin mô tả các trường của nó; phần dưới đây chỉ nói về những gì bản build tự làm với nó.
Một bản build bị đối chiếu với bản ghi trước khi bất kỳ plugin nào trong số đó chạy. Một plugin được phục vụ từ cache mà digest artifact không phải là digest đã ghi sẽ bị từ chối thay vì được chạy — đó là cách phân giải mà một attachment như vậy thường dùng, và aggrega pull trình bày những cách phân giải khác mà digest đã ghi không chi phối. Và một mục đã ghi mà không còn attachment nào trong .aggrega-config.yaml tương ứng sẽ làm dừng bản build: bỏ một cổng kiểm soát không thay đổi byte render nào, nên đầu ra tạo ra khi thiếu một cổng đã được xem xét trông giống hệt đầu ra mà cổng đó đã chấp thuận. Thông báo dừng nêu tên plugin và đưa ra hai cách khắc phục tùy theo ý định của bạn — gắn lại nó nếu việc gỡ bỏ là nhầm lẫn, hoặc yêu cầu gỡ bỏ một cách tường minh nếu không phải — và in ra lệnh sẵn sàng để chạy. Một attachment mà bản ghi chưa có là lần xuất hiện đầu tiên, và không phép so sánh nào dừng vì nó.
Một bản build đối chiếu mỗi plugin đó với chữ ký mà mục của nó ghi lại, giống hệt cách nó đối chiếu một mục lockfile với giá trị mà mục đó ghi lại. Khi một mục ghi một signature đã được xác minh, bản build băm lại gói chữ ký mà thông tin đó chỉ tới trong cache trước khi render bất cứ thứ gì, và dừng với E0144 khi gói bị thiếu hoặc khác. Với một plugin đọc từ content cache, bản build còn đọc từ gói đó xem chữ ký được tạo cho artifact nào, và dừng với E0332 khi nó được tạo cho một plugin khác với plugin mà bản build đã đọc — đó chính là dấu hiệu của một signature được sao chép từ mục khác — bất kể yêu cầu ký nói gì. Với một plugin do content cache phục vụ, cả hai lần từ chối đều nêu aggrega pull --release <release>: lần pull kế tiếp xác minh lại chữ ký của plugin, ghi lại chữ ký của chính plugin đó và lưu cache gói mà nó chỉ tới, ghi đè bản sao trong cache không còn khớp với digest. Khi cấu hình tin cậy của workspace yêu cầu chữ ký cho một plugin mà bản build đọc từ content cache — theo cùng các thiết lập khiến aggrega pull từ chối nó khi chưa ký, nên skip_signature_verification và một registry advisory cho phép bản build tiếp tục như chúng cho phép lần pull — thì một mục không ghi chữ ký, hoặc hoàn toàn không có mục cho plugin đó, sẽ dừng bản build với E0331, nêu tên plugin, plugins-trust.yaml và các thiết lập yêu cầu chữ ký. Cách khắc phục là aggrega pull --release <release>, lệnh này xác minh chữ ký của plugin tại registry của nó mỗi lần chạy và ghi lại. Một plugin được phục vụ từ một trong các thư mục catalog của bạn, hoặc từ bản sao bên trong binary của trình biên dịch, không bao giờ chịu yêu cầu đó. Giống như phần còn lại của bản build, việc này đọc các tệp đã có trên máy và không hỏi registry nào điều gì.
Bản build nêu tên mọi lần rút lại mà bản ghi mang, bên cạnh mọi lần rút lại mà lockfile mang. Một marker mà aggrega pull đã ghi đối với một trong các plugin đó được báo cáo thành một dòng deprecation: nêu tên plugin, mức độ nghiêm trọng đã ghi và thông điệp của nhà phát hành, ở mọi mức độ nghiêm trọng, và build.halt_on_deprecated_severity quyết định liệu nó có đồng thời dừng bản build hay không, theo cùng quy tắc mà nó áp dụng cho một tham chiếu đã ghim. Mọi bề mặt khác báo cáo về một Release đều nêu tên cùng tập hợp đó bằng cùng câu chữ, và không bề mặt nào dừng lại vì nó: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, câu trả lời về xác thực và bao đóng của language server, và describe và validate của các công cụ trợ lý. Một bản ghi có tồn tại nhưng không đọc được sẽ dừng bản build thay vì được cho qua như một bản ghi không ghi nhận gì.
aggrega build --upgrade ghi lại tệp đó. Nó ngụ ý --auto-pull và chạy một lần làm mới toàn bộ trần, phân giải lại mọi dependency, do đó phân giải lại và ghi lại mọi định danh đã ghi, đồng thời bỏ mọi mục không có attachment nào tương ứng. Vì vậy nếu tệp này bị thay đổi sau một bản build upgrade, đó là lý do: phạm vi của cờ là mọi dependency, và các định danh đã ghi là một phần của những gì được phân giải lại dù chúng không phải pin của lockfile. Khác với aggrega pull --upgrade, cờ của build không nhận đích, nên không thể thu hẹp về một plugin: để chấp nhận hoặc bỏ một định danh duy nhất, hãy chạy aggrega pull --upgrade --release <release> <plugin> thay vào đó, lệnh này giữ nguyên mọi pin khác và mọi định danh đã ghi khác.
Vì phạm vi của nó là mọi thứ, nó hỏi trước khi bắt đầu. aggrega build --upgrade xác nhận lần làm mới theo cùng điều kiện như aggrega pull --upgrade trần — hai lệnh là cùng một hành động, nên chúng hỏi cùng một câu hỏi. Truyền --yes để trả lời trước khi dùng không tương tác; khi đầu vào chuẩn không phải là terminal và không có --yes, bản build từ chối thay vì chờ một câu trả lời mà không ai có thể đưa ra. Một bản build không làm mới thì không hỏi gì.
Phân giải workspace và tính tất định
Tham chiếu manifest: mà schema của Release yêu cầu được phân giải tương đối với tệp
Release. Một mục catalog_dirs tương đối (và một đường dẫn plugin tương đối trên hệ thống tệp) được phân giải
theo thư mục của tệp .aggrega-config.yaml đã khai báo nó — “tương đối”
luôn có nghĩa là tương đối với tệp mà bạn viết nó vào, nên một đường dẫn mang cùng một
nghĩa dù bạn gọi aggrega từ đâu. Cờ --catalog, vốn không có
tệp khai báo, được phân giải theo thư mục làm việc hiện tại. Các tham chiếu
registry (oci://…, một tham chiếu hub) được giữ nguyên.
Gốc workspace là thư mục của tệp .aggrega-config.yaml tổ tiên gần nhất có khối workspace:, hoặc thư mục mà --workspace-root chỉ định. Khi gốc được cố định theo cách này, một bản build không phụ thuộc vào vị trí gọi lệnh: chạy aggrega build từ gốc dự án và từ một thư mục con tạo ra IR và các artifact đã render giống hệt nhau đến từng byte, vì catalog được tìm kiếm và các đường dẫn nguồn ghi trong đầu ra không thay đổi theo thư mục làm việc. (Khi không có dấu hiệu workspace: và không có --workspace-root, thư mục làm việc là gốc, nên đầu ra được neo tại đó — trừ khi thư mục làm việc không neo gì và --release chỉ định Release bằng một đường dẫn tuyệt đối: khi đó gốc được tìm lại từ chính thư mục của Release, nên catalog được tìm kiếm và các đường dẫn ghi trong đầu ra là của dự án mà Release thuộc về, dù bạn chạy lệnh từ đâu. Xem configuration.md.) Khi cách đó cũng không tìm thấy workspace nào và không có gì chỉ định một workspace, bản build cảnh báo trên standard error rằng thư mục đã được dùng làm gốc không nằm trong workspace nào, và nêu lệnh biến nó thành một workspace; một bản build được yêu cầu phân giải các phụ thuộc trước sẽ bị từ chối trước khi bất cứ thứ gì được tải về, vì bộ nhớ đệm mà quá trình phân giải đó lấp đầy sẽ được ghi vào thư mục đó và biến nó thành một workspace. Một bản build không phân giải gì trước vẫn render, nhưng vì cùng lý do đó, một đầu vào bên ngoài mà lockfile ghim và bộ nhớ đệm không còn giữ sẽ không được tải lại: plugin yêu cầu nó nhận câu thông báo từ chối thay vào đó, giống như nó nhận câu thông báo của chế độ ngoại tuyến, và bản build báo cáo plugin đó xử lý điều này ra sao. Một --workspace-root hoặc AGGREGA_WORKSPACE_ROOT chỉ định một thư mục không tồn tại sẽ bị từ chối trước khi bản build làm bất cứ điều gì khác, kèm tên của cái nào trong hai cái đã cung cấp nó.
Biến môi trường
Các thiết lập workspace mà build đọc có thể được ghi đè qua môi trường, ở mức ưu tiên cao hơn cấu hình đã commit và thấp hơn mọi flag: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (danh sách đường dẫn phân tách theo dấu phân cách của hệ điều hành; hãy cung cấp đường dẫn tuyệt đối), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY và AGGREGA_WORKSPACE_ROOT. Xem environment-variables.md để biết danh sách đầy đủ và mô hình thứ tự ưu tiên.
Đầu ra
Các artifact được kết xuất sẽ nằm trong dist/ bên dưới thư mục gốc của workspace, bất kể lệnh được chạy từ thư mục nào — chính thư mục gốc, một thư mục bên dưới nó, hay một thư mục ở nơi khác với thư mục gốc được chỉ định bởi --workspace-root hoặc AGGREGA_WORKSPACE_ROOT — và dòng kết thúc ghi đầy đủ tên thư mục đó:
Build completed: 4 files written to <workspace>/dist<workspace> ở đây đại diện cho thư mục gốc của workspace, mà dòng này ghi ra dưới dạng đường dẫn đầy đủ. Khi không tìm thấy workspace nào và không có gì chỉ định workspace, thư mục mà lệnh được chạy từ đó chính là thư mục gốc, vì vậy dist/ được ghi tại đó. Một dist là liên kết dẫn ra ngoài workspace sẽ bị từ chối trước khi bất kỳ thứ gì trong đó bị xóa hoặc được ghi. Một Release không khai báo boundary nào sẽ ghi theo từng provider: dist/<provider>/<files>. Một boundary được khai báo mà không có directory: sẽ ghi theo từng boundary, theo từng provider: dist/boundaries/<boundary-path>/<provider>/<files>. Các giá trị ghi đè directory: và subDirectory: do operator viết trên các boundary của Release sẽ thay đổi đường dẫn đích; việc gộp theo từng (path, provider) hợp nhất các thành phần đóng góp được phân giải về cùng một đường dẫn đã đánh giá.
Các tệp mà bản build không ghi
Một bản build ghi các tệp của chính nó và không xóa gì mà nó không ghi, với một ngoại lệ: dist/boundaries/, thư mục mà bản build tạo lại toàn bộ, được dọn sạch trước khi ghi, để một tệp mà bản build của một biến thể khác để lại ở đó không tồn tại sang một cây không còn tạo ra nó. Mọi thứ khác trong dist/ được giữ nguyên — dù là một tệp mà một bản build trước đã ghi nhưng bản build này không còn tạo ra, một tệp mà directory: của một ranh giới đã đặt ở đó trong một lần chạy trước, hay một tệp bạn tự đặt vào đó — vì bản build không thể phân biệt một tệp sót lại với một tệp bạn cố ý giữ ở đó.
Thay vào đó, nó cho bạn biết. Sau khi ghi xong các tệp của mình, bản build xem xét chính dist/ và mọi thư mục bên dưới nó mà nó đã ghi một tệp vào hoặc đã đi qua để ghi một tệp sâu hơn, rồi nêu tên từng tệp ở đó mà nó không ghi trong lần chạy này, trong một cảnh báo duy nhất trên standard error. Các tệp được nêu tên theo đường dẫn tương đối với dist/, đã sắp xếp, nên cùng một cây được báo cáo theo cùng một cách ở mọi lần chạy:
warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"Sau đó, dòng kết thúc đếm số lượng của chúng:
Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not writeMột thư mục mà bản build không ghi gì vào, và cũng không ghi gì bên dưới, sẽ không được xem xét, nên một thư mục riêng của bạn được giữ dưới dist/ sẽ không bị liệt kê từng tệp. Một bản build không tìm thấy tệp nào như vậy sẽ không in cảnh báo, và dòng kết thúc của nó là dòng được hiển thị trong Đầu ra. Dù thế nào, các tệp mà bản build ghi đều là cùng các byte. Để so sánh hai bản build, hoặc để bắt đầu từ đầu, hãy xóa dist/ trước khi build.
Yêu cầu aggrega/build của aggrega serve và công cụ build của trợ lý (aggrega mcp) ghi qua cùng một bước, nên chúng nêu tên cùng các tệp trong cùng một câu: daemon như một trong các notices của câu trả lời, còn công cụ như mục cuối cùng trong advisories của nó. Một lần chạy thử không ghi gì, nên không báo cáo điều nào trong số này.
Thụt lề YAML
Mọi artifact YAML được kết xuất — các tệp docker-compose, template và values của Helm chart, và các manifest Kubernetes — đều được xuất ra với độ rộng thụt lề thống nhất. Độ rộng này được đặt bởi build.yaml_indent trong .aggrega-config.yaml và mặc định là 2 (độ rộng theo quy ước cho các định dạng đó):
build: yaml_indent: 2 # default; accepts 2 through 9Độ rộng được áp dụng tại một điểm marshal duy nhất dùng chung cho mọi renderer, nên đầu ra giữ nguyên từng byte qua các lần chạy với cùng đầu vào. Các giá trị nằm ngoài khoảng [2, 9] bị từ chối bởi bước xác thực config-schema.
Trả lại đồ thị đã biên dịch
--ir-graph ghi đồ thị mà bản build này đã phân giải ra đầu ra chuẩn dưới dạng JSON. Nó mang tính bổ sung: các artifact vẫn được ghi vào dist/, bản tóm tắt vẫn được in ra, và các byte được kết xuất không thay đổi. Đồ thị được xuất ra trước mọi thứ khác mà bản build in ra đó — một tài liệu JSON và một ký tự xuống dòng ở cuối — để bên tiêu thụ giải mã luồng sẽ đọc nó rồi dừng.
Đồ thị được trả lại chính là đồ thị mà bước kết xuất đã sử dụng, nên nó mô tả chính xác bản build đã tạo ra các artifact bên cạnh nó, chứ không phải một lần phân giải thứ hai của cùng Release. Nó kết hợp được với --dry-run: đồ thị được ghi ra và báo cáo artifact theo sau, không có gì được ghi xuống đĩa.
Các giá trị mà tác giả đã khai báo là nhạy cảm sẽ bị giữ lại khỏi đồ thị — bao gồm cả values và infra của một kết nối, khi socket của component tiêu thụ khai báo một lá là nhạy cảm — theo dạng có cấu trúc được mô tả tại aggrega inspect. --unredacted đi cùng --ir-graph sẽ in chúng ra thay vào đó, theo các điều kiện mà aggrega inspect --unredacted nêu: nó chỉ tác động đến đồ thị và không gì khác — các tệp trace có --trace-unredacted riêng, và các artifact được kết xuất không bao giờ bị giữ lại — và bất cứ nơi nào đầu ra đi tới khi đó sẽ mang các giá trị đó ở dạng rõ. Nếu được truyền mà không có --ir-graph thì nó bị từ chối, vì sẽ không có gì để nó tiết lộ.
Cờ tương tự, với cùng ý nghĩa, có trên aggrega inspect và aggrega validate.
Xem trước một bản build mà không ghi ra
--dry-run chạy cùng quá trình biên dịch mà một bản build chạy — cùng các cổng kiểm tra phụ thuộc, cùng bước render, cùng các provider — và in ra những gì nó sẽ xuất thay vì ghi ra. Mỗi artifact được báo cáo cùng đường dẫn mà nó sẽ chiếm và nội dung mà nó sẽ chứa:
aggrega build --release releases/production.yaml --dry-run==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==apiVersion: v1kind: ConfigMap...
Total build time: 2.5sDry run: 1 file would be written to <workspace>/dist; nothing was writtenCác artifact được báo cáo theo thứ tự mà một bản build ghi chúng, nên cùng một đầu vào sẽ báo cáo cùng các byte theo cùng một trình tự, và đường dẫn được báo cáo chính là đường dẫn mà một bản build sẽ ghi vào — bên dưới thư mục gốc của workspace, được viết đầy đủ ở chỗ <workspace> đứng ở trên.
Những gì không được ghi. Thư mục đầu ra được giữ nguyên đúng như hiện trạng — nó cũng không bị dọn sạch, nên đầu ra của một bản build trước đó vẫn còn nguyên vẹn sau một lần chạy thử. Lockfile không được ghi. Không có gì được ghi vào .trace/.
Các đầu vào bên ngoài hoạt động đúng như trong một bản build thông thường, theo các điều kiện mà Đầu vào bên ngoài khi build đặt ra. Do đó, một lần chạy thử đọc cùng tập đóng đã được ghim mà bản build nó thay thế sẽ đọc, và những gì nó hiển thị chính là những gì bản build đó sẽ ghi.
Khi một tham chiếu bị từ chối, lần chạy sẽ nêu tên mọi tham chiếu mà nó không thể truy cập và chỉ đến lệnh ghim chúng:
note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit: - https://charts.example.com/values-schema.json Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run againChạy aggrega pull một lần là lần chạy thử có mọi thứ nó cần; không có gì khác về nó thay đổi.
Một lần chạy thử cần một lockfile và không bao giờ điền vào lockfile. Theo mặc định, build chỉ đọc, và một lần chạy thử giữ nguyên điều đó bất kể việc điền được yêu cầu theo cách nào. --auto-pull và --upgrade bị từ chối hoàn toàn (xem bên dưới); thiết lập workspace auto_pull bị ghi đè cho riêng lần gọi đó, nên một workspace mặc định có điền lockfile vẫn có thể được xem trước. Khi không có lockfile, một lần chạy thử dừng lại với cùng cách khắc phục mà một bản build chỉ đọc thông thường đưa ra: chạy aggrega pull trước.
Các cờ mà nó từ chối. Ba cờ có ghi dữ liệu, nên việc kết hợp chúng với một lần chạy thử không có kết quả trung thực nào — bỏ qua thao tác ghi sẽ làm một yêu cầu điền biến mất, còn thực hiện nó sẽ phá vỡ lời hứa duy nhất mà lần chạy thử đưa ra. Mỗi cách kết hợp đều dừng lại trước khi làm bất kỳ việc gì, nêu tên cờ bạn đã truyền và bước cần chạy thay thế:
| Kết hợp với | Lý do từ chối |
|---|---|
--auto-pull | điền vào lockfile; hãy chạy aggrega pull như một bước riêng |
--upgrade | phân giải lại mọi phụ thuộc và ghi lại lockfile; hãy chạy aggrega pull --upgrade như một bước riêng |
--trace | ghi các tệp theo từng node vào .trace/; hãy chạy bản build có trace mà không dùng --dry-run |
Mọi thứ khác kết hợp bình thường. --verify-determinism render mỗi node hai lần và so sánh các byte mà không ghi bất kỳ byte nào, còn --catalog, --quiet, --progress, --debug và các bộ lọc cảnh báo hoạt động đúng như trên một bản build có ghi.
Nó dùng để làm gì, và không dùng để làm gì. Một lần chạy thử trả lời câu hỏi “Release này sẽ xuất ra gì”, một câu hỏi chỉ bước render mới trả lời được — nên nó không thay thế cho aggrega validate, lệnh kiểm tra tính đúng đắn mà không render, hay cho aggrega inspect, lệnh truy vấn đồ thị trước khi render. Hãy dùng một lần chạy thử khi câu trả lời bạn muốn chính là các artifact: xem xét một thay đổi Release ảnh hưởng thế nào đến đầu ra, hoặc kiểm tra một chỉnh sửa Recipe trước khi đưa bất cứ thứ gì vào dist/.
Đầu ra trace
Cờ --trace bật chế độ kết xuất gỡ lỗi theo từng node, ghi lại mọi trạng thái trung gian của trình biên dịch. Đầu ra nằm tại .trace/ bên dưới thư mục gốc của workspace, cạnh dist/ (không bao giờ nằm trong nó; bố cục ngang hàng này theo quy ước của .git/, .terraform/, node_modules/ và giữ cho dist/ chỉ chứa những gì có thể triển khai).
Bố cục thư mục được chia theo từng ranh giới, từng instance:
.trace/└── boundaries/ └── <boundary-path>/ └── <instance-id>/ ├── 01-pillars-initial.yaml ├── 02-provides-evaluation.yaml ├── 03-inject-hydration.yaml ├── 04-inject-mapping.yaml ├── 05-source-resolution.yaml ├── 06-source-locals.yaml ├── 07-values-mapping.yaml ├── 08-workload-synthesis.yaml ├── 09-artifact-evaluation/ │ └── <per-artifact-file>.yaml ├── 09b-feature-rendering-boundary.yaml ├── 10-engine-synthesis/ │ └── <per-synthesized-file>.yaml ├── 11-engine-emission.log └── 12-labels-injected.logMỗi slot ghi lại một trạng thái cụ thể của trình biên dịch:
01-pillars-initial.yaml— ảnh chụp theo từng node của ngữ cảnh mà template đọc, được lấy sau khi phân giải và trước mọi thay đổi theo từng giai đoạn. Chứa.values,.infra,.context,.parameters,.metadata.02-provides-evaluation.yaml— các đầu raprovides:đã được phân giải sau bước đánh giá provides.03-inject-hydration.yaml— pipe.context.injectđã hợp nhất sau bước hydration inject (góc nhìn phía bên tiêu thụ đối vớiprovidesở thượng nguồn).04-inject-mapping.yaml— pipe.context.injectsau các bước viết lạiinjectMappingcủa FeatureRecipe.05-source-resolution.yaml— nội dungsource:đã được phân tích mà provider sẽ tiêu thụ. Chỉ có khi Recipe khai báosource:.06-source-locals.yaml— khốilocals:đã được phân giải. Bước phân giải source công bố.localstrước khi đánh giá templatesource:, đó là lý do slot này được ghi dù Recipe có khai báosource:hay không.07-values-mapping.yaml— đầu ravaluesMapping:đã được render (dictionary mà provider nhận được). Chỉ có khi Recipe khai báovaluesMapping:.08-workload-synthesis.yaml— context tại thời điểm templateworkload:được đánh giá và đầu ra của nó được phân tích. Chỉ có khi Recipe khai báoworkload:(inline hoặc được nạp bằng$import:). Bản thânWorkloadđã phân tích không nằm trong slot này: nó xuất hiện từ09-artifact-evaluation/trở đi, khi đã ổn định chứ không còn đang xử lý.09-artifact-evaluation/— mỗi artifact được đánh giá có một tệp. Chỉ có khi Recipe khai báoartifacts:(với các mục inline hoặc từng mục được nạp bằng$import:).09b-feature-rendering-boundary.yaml— ngữ cảnh lúc quá trình render của node kết thúc, khi các FeatureRecipes được gắn vào node đã sinh ra tài nguyên của chúng, vớiworkloadđã phân tích nằm bên cạnh. Được ghi cho mọi node.10-engine-synthesis/— mỗi manifest được tổng hợp mà provider tạo ra từ Workload có một tệp (chế độ workload của helm/compose). Chỉ có khi provider chạy một đường tổng hợp.11-engine-emission.log— bản tóm tắt sau khi xuất (số lượng tệp, đường dẫn đầu ra) của node.12-labels-injected.log— các label và annotation về nguồn gốc được ghi vào đầu ra đã render của node.
Từ 03-inject-hydration.yaml trở đi, một slot hiển thị ngữ cảnh của node sẽ mang khối .context.inject bất cứ khi nào đường ống mà nó ghi lại phân phối ít nhất một khóa, dưới bất kỳ cơ chế nào: env, file, arg, hoặc một cơ chế mang tên khác mà một mapping inject, injectMapping của một FeatureRecipe hoặc khối inject: của chính thành phần đó ghi vào. Một node mà việc phân phối duy nhất là một cơ chế tùy chỉnh như vậy cũng hiển thị khối này, với cơ chế đó dưới chính tên của nó và các khóa của nó trong all, và một giá trị được khai báo nhạy cảm hiển thị là <redacted> ở cả hai nơi. Một slot được ghi lại khi đường ống không phân phối gì thì không có khối .context.inject.
Bộ ghi trace không chặn: trace được ghi xuống đĩa song song với quá trình biên dịch thay vì nằm trên đường đi của nó. Độ trễ biên dịch không bị ảnh hưởng bởi I/O của trace — cùng một lần biên dịch hoàn tất trong cùng thời gian thực dù --trace bật hay tắt.
Các giá trị được khai báo là nhạy cảm trong trace
Một dữ liệu mà tác giả đã khai báo là nhạy cảm — một lá schema mang sensitive: true, hoặc một khóa phân phối có nội dung đến từ một khóa provides mang khai báo đó — được ghi vào trace dưới dạng văn bản cố định <redacted>. Khóa được giữ lại và chỉ giá trị bị thay thế, nên một slot vẫn cho thấy một node mang những lá nào và những khóa phân phối nào. Một phần tử anh em không được khai báo trong cùng khối sẽ in giá trị của nó nguyên văn; việc thay thế chỉ dựa theo khai báo và không gì khác.
Một giá trị mà một FeatureRecipe phân phối qua injectMapping của chính nó cũng bị che. Đó là con đường mà một slot khai báo danh sách inject rỗng giao việc phân phối cho, và là con đường mà một hiện thực hóa thông tin xác thực chỉ dùng inject đi theo. Bản thân khóa phân phối mà một mapping như vậy ghi ra là một template, nên không khai báo nào gọi tên nó; thứ được đọc thay vào đó là chính văn bản của mapping. Khi văn bản đó tham chiếu đến một lá values hoặc infra mà Feature được gắn khai báo sensitive: true, mọi khóa phân phối mà mapping tạo ra đều hiển thị là <redacted> — kể cả một khóa không mang gì nhạy cảm, vì việc đọc diễn ra theo từng lần gắn chứ không theo từng khóa. Một mapping không tham chiếu đến gì được khai báo sẽ in các khóa của nó nguyên văn.
Một giá trị mà template tính toán từ một dữ liệu được khai báo là nhạy cảm cũng bị che, dù bản thân khóa của nó không mang khai báo nào. Thứ nhận diện nó là tham chiếu mà tác giả đã viết: một mục locals: có template đọc một lá được khai báo là nhạy cảm sẽ bị che, và một trường source: làm điều đó cũng vậy. Cách đọc này mang tính thận trọng — một template chạm đến cả một đối tượng thì chạm đến mọi lá được khai báo bên dưới nó, nên {{ range $k, $v := .values.creds }} sẽ che đầu ra của nó khi bất cứ thứ gì bên dưới creds được khai báo — và một mục locals: đọc một phần tử anh em đã bị che thì đến lượt nó cũng bị che. Một mục anh em có cùng dạng nhưng không đọc gì được khai báo sẽ in nguyên văn.
Một giá trị đi qua một cạnh uses bị che theo các khai báo của đích, không phải của node tiêu thụ, và nó bị che trên cả hai bề mặt mà cạnh đưa nó đến. .context.uses.<alias>.provides tái hiện những gì component đích đã công bố, nên thứ chi phối các giá trị đó là schema của đích: một khóa provides mà đích khai báo là nhạy cảm sẽ hiển thị là <redacted> trên slot của bên tiêu thụ ngay cả khi bên tiêu thụ không khai báo gì cả. Khi khối inject của chính cạnh định tuyến khóa đó vào một khóa phân phối của component tiêu thụ, .context.inject cũng che khóa phân phối đó — cùng quy tắc mà mapping inject của một lần gắn đã tuân theo, đọc cùng một khai báo. Việc che diễn ra theo từng cạnh, nên hai cạnh công bố cùng một tên khóa provides được phân giải độc lập: cạnh có đích đã khai báo nó thì bị che, còn cạnh kia in nguyên văn. Phần còn lại của cạnh — đích của nó, socket của nó, các nhãn của nó và chính các tên khóa của mapping inject — không thuộc phạm vi mà khai báo provides của đích chi phối, và được in nguyên văn.
Còn các values và infra theo từng kết nối được viết trên chính cạnh thì do socket của component tiêu thụ chi phối: valueSchema và infraSchema mà socket đó khai báo, vốn là các hợp đồng dùng để xác thực cấu hình đó. Một lá mà một trong hai hợp đồng khai báo sensitive: true sẽ hiển thị là <redacted> tại .context.uses.<alias>.values hoặc .context.uses.<alias>.infra, khóa vẫn được giữ, và một lá đang ở giá trị mặc định do hợp đồng khai báo cũng vậy; một lá anh em không được khai báo được in nguyên văn. Các khai báo của đích không đóng vai trò gì ở đây, và việc che diễn ra theo từng kết nối, nên một lá cùng tên trên một kết nối có socket khai báo nó là đọc được sẽ được in nguyên văn.
Các lần gắn được viết trên một kết nối được hiển thị dưới cạnh của kết nối đó, tại .context.uses.<alias>.features.<slot>, và mỗi lần gắn bị che theo các khai báo của chính Feature của nó — cũng chính các khai báo chi phối Feature đó khi một component giữ nó trực tiếp. Một lá values hoặc infra mà Feature khai báo sensitive: true sẽ hiển thị là <redacted>, và một khóa thuộc provides đã phân giải của lần gắn mà Feature khai báo là nhạy cảm cũng vậy; mỗi khóa đều được giữ lại. Kiểu, phiên bản và nhãn của lần gắn, cùng mọi lá và khóa provides mà Feature của nó không khai báo, được in nguyên văn, nên một bộ định vị đã công bố vẫn đọc được bên cạnh nội dung mà nó định vị. Việc che diễn ra theo từng kết nối và slot, nên cùng một Feature được viết trên hai kết nối sẽ được phân giải trên mỗi kết nối. Một slot khai báo sensitive: true — trên component hoặc trên socket của nó — cho biết lần gắn xử lý nội dung bí mật và tự nó không che lá nào: những lá nào bị che là do Feature khai báo. Các lần gắn của chính một component không nằm trong số các khối mà slot hiển thị, vì trace không mang khối .features nào; những gì một template workload: đọc từ một lần gắn như vậy được bao quát bởi bản render lại dưới đây.
Workload đã phân tích là một bản render lại, không phải bản ghi lại tài liệu mà bản build đã xuất ra, và các slot mang nó — 09-artifact-evaluation/, 10-engine-synthesis/ và 09b-feature-rendering-boundary.yaml — nói rõ điều đó trong một mục workload_note bên cạnh. Một tài liệu đã render không ghi lại gì về việc một ký tự cụ thể đến từ khai báo nào, nên không có khóa nào để thay thế bên trong nó. Thay vào đó, trace hiển thị cùng template workload: được đánh giá lần thứ hai, với một ngữ cảnh mà dữ liệu được khai báo là nhạy cảm đã hiển thị là <redacted>. Vì template thấy một chuỗi ở nơi vốn là một chuỗi, kết quả giữ nguyên hình dạng của tài liệu đã xuất: cùng các trường, ở cùng vị trí, với <redacted> đứng đúng vị trí của dữ liệu bị che và văn bản cố định xung quanh không đổi.
Hai điểm mà bản render lại đó khác với những gì đã được xuất ra, cả hai đều được ghi chú nêu rõ:
- Một template rẽ nhánh theo nội dung của một giá trị sẽ render khác đi. Một phép
eqso với một giá trị cụ thể, một phép kiểm tra độ dài, một hàm băm hay một phép mã hóa giá trị đó: mỗi thứ đều thấy<redacted>và tạo ra kết quả khác — một nhánh khác, một độ dài khác, một digest khác. Đây là lý do trace không bao giờ tuyên bố hiển thị tài liệu đã xuất. - Dữ liệu không được khai báo nào gọi tên sẽ được giữ nguyên. Việc thay thế bao gồm những gì trục này gọi tên — một lá
values/infrađược khai báo, một khóa phân phối được đánh dấu, một khóaprovidesmà chính Component của component khai báo là nhạy cảm,providesđược khai báo của một đích được tiêu thụ, một lá trongvalueshoặcinfrariêng của một kết nối mà socket của nó khai báo là nhạy cảm, một lá hoặc khóaprovidesđược khai báo của một lần gắn mà component tự giữ (đọc tại.features.<name>) hoặc của một lần gắn được viết trên một kết nối, và một giá trịlocals:hoặcsource:được tính từ một trong số đó. Đó cũng chính là dữ liệu mà một lời từ chối do template đưa ra bị che theo. Một dữ liệu đến template qua bất kỳ đường nào khác, chẳng hạn một khóaprovideskhông được khai báo nào gọi tên mà giá trị của nó do một Recipe tính từ một lá được khai báo, sẽ xuất hiện trong bản render lại đúng như nó xuất hiện trong tài liệu đã xuất.
Khi hoàn toàn không thể tạo ra bản render lại, slot giữ khóa workload: và thay tài liệu bằng một dòng nói rõ điều đó và nêu tên --trace-unredacted. Lời thông báo này là có chủ ý: một phép chiếu chỉ đơn giản biến mất sẽ không thể phân biệt được với một Recipe không khai báo workload: nào.
Có một giới hạn đáng đọc trước khi coi .trace/ là an toàn: dist/ không được che. Các artifact đã render được xuất ra đúng như quá trình render tạo ra, vì chúng là thứ để triển khai, và bản render lại của trace không bao giờ chạm đến chúng — cùng một đầu vào render ra giống hệt từng byte dù --trace bật hay tắt.
Hãy coi .trace/ là nơi chứa nội dung nhạy cảm và xử lý nó theo cách xử lý dist/.
Hiển thị các giá trị bị che
--trace-unredacted, khi dùng cùng --trace, ghi các giá trị được khai báo là nhạy cảm vào các tệp trace thay cho đoạn văn bản đứng thay chúng. Cờ này tồn tại vì đôi khi chính giá trị bị che lại là thứ đang cần gỡ lỗi — một thông tin xác thực đến từ attachment sai trông giống hệt thông tin đến từ attachment đúng khi cả hai đều hiển thị là bị che.
Đây cũng là cách ghi lại tài liệu mà bản build thực sự đã xuất ra: khi không có gì bị che thì không có gì để thay thế, nên các slot workload: chứa tài liệu đã xuất thay vì một bản render lại của nó, và mục workload_note không xuất hiện.
Ba thuộc tính giới hạn cờ này:
- Mọi tệp nó ghi đều tự nói rõ mình là gì. Mỗi tệp trace mà lần chạy tạo ra đều mở đầu bằng một chú thích nêu tên cờ và cho biết các giá trị được khai báo là nhạy cảm xuất hiện bên dưới ở dạng rõ, nên một tệp sau này được đính kèm vào báo cáo lỗi hoặc bị để lại trong một thư mục dùng chung vẫn mang theo cảnh báo của chính nó. Chú thích này hợp lệ theo định dạng của chính tệp, nên tệp vẫn phân tích cú pháp được.
- Nó chỉ tác động đến
.trace/và không gì khác. Các artifact được render giống hệt nhau từng byte dù có hay không có cờ này — nó thay đổi những gì một tệp gỡ lỗi hiển thị, không bao giờ thay đổi những gì một bản build tạo ra — và các bố cục củaaggrega inspectcũng như văn bản chẩn đoán mà một bản build thất bại in ra đều giống hệt nhau ở cả hai trạng thái. - Nó chỉ tồn tại trên lần gọi lệnh. Không có thiết lập cấu hình nào cho nó, nên không thể bật một lần rồi để nguyên cho tất cả những ai build workspace sau đó. Yêu cầu cờ này mà không có
--tracesẽ dừng bản build với một thông báo nêu tên cả hai cờ, thay vì chấp nhận một yêu cầu mà nó không thể đáp ứng.
Tách biệt với trace, một bản build in ra một cảnh báo tư vấn cho mỗi delivery key mang tài liệu được khai báo là nhạy cảm dưới dạng giá trị literal, nêu tên component, target, attachment và delivery key. Cảnh báo này không bao giờ dừng bản build và --no-unsupported-field-warnings không tắt được nó — cờ đó bao quát những gì một target không thể đáp ứng trong số những thứ bạn đã viết, một loại khác.
Từ khóa, hai vị trí viết nó, nội dung chính xác của cảnh báo tư vấn và toàn bộ giới hạn của những gì việc khai báo nó đạt được có tại vocabulary/compact-form-authoring.md “Declaring a leaf sensitive”.
Khi nào dùng --trace
- Chẩn đoán vì sao một manifest đã kết xuất không mang một giá trị mong đợi: duyệt qua các bản kết xuất theo từng lượt để tìm slot đầu tiên mà giá trị bị thiếu.
- Xác minh tính tất định sau khi nâng cấp trình biên dịch: hai lần biên dịch cùng một đầu vào với
--tracetạo ra các bản kết xuất trace giống hệt nhau đến từng byte; bất kỳ khác biệt nào theo từng slot đều khoanh vùng được lỗi hồi quy. - Lặp lại trong quá trình soạn catalog: so sánh các ảnh chụp
04-inject-mapping.yamlvà06-source-locals.yamlcho thấy các template của Recipe nhìn thấy gì tại thời điểm đánh giá.
Ví dụ
Biên dịch một Release dựa trên catalog cục bộ:
aggrega build --release releases/production.yamlBiên dịch với một thư mục catalog riêng:
aggrega build --release releases/production.yaml --catalog ../platform-catalog/Xem một Release sẽ xuất ra những gì mà không ghi bất kỳ phần nào:
aggrega build --release releases/production.yaml --dry-runBiên dịch kèm các bản kết xuất trace để gỡ lỗi:
aggrega build --release releases/production.yaml --traceSau khi biên dịch, hãy kiểm tra .trace/boundaries/<boundary>/<instance>/ để xem trạng thái theo từng pass. Thư mục .trace/ bị ghi đè ở mỗi lần chạy --trace; trạng thái trace trước đó không được giữ lại giữa các lần biên dịch.
Tham chiếu chéo
aggrega-pull— tải các thực thể catalog từ một OCI registry vào catalog cục bộ.aggrega-validate— kiểm tra tính đúng đắn của catalog, của bao đóng Release hoặc của một thực thể đơn lẻ mà không phát sinh artifact; tức là bước xác thực phụ thuộc mà một lần build chạy, nhưng không render.aggrega-lint— kiểm tra các quy ước xuất bản catalog trên cùng ba phạm vi đó.aggrega-inspect— truy vấn đồ thị IR sau khi hoàn tất đồ thị mà không tiếp tục sang bước render.- Lỗi — định dạng hiển thị lỗi theo phân loại xuất hiện ở CLI.
Cú pháp
aggrega build [flags]Mô tả
Compile an Aggregate and Release pair into provider-native artifacts under eachboundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,declares the boundaries, and routes each component to a provider. What aprovider emits is the provider's own shape — Helm manifests, a redistributableHelm chart, docker-compose YAML — so the output directory holds whatever theproviders this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder thecommand is run from, and the closing line names it in full. A run that finds noworkspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first tocreate one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makesthe rendered tree reviewable as a diff.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--auto-pull | false | Chạy bước pull trước khi build: phân giải các phụ thuộc của Release vào lockfile và cache ngay trong tiến trình, rồi build dựa trên chúng. Đây chính là bước điền trong tiến trình mà thiết lập auto_pull của workspace thực hiện, được bật cho một lần build duy nhất mà không cần sửa cấu hình workspace. Khi dùng riêng, đây là một lần điền tăng dần — các pin hiện có được tôn trọng, còn các tham chiếu chưa có pin sẽ được phân giải và thêm vào |
--catalog | [] | Thư mục catalog; có thể lặp lại. Mỗi —catalog <dir> được thêm vào đầu ngăn xếp tìm kiếm catalog (kết quả khớp đầu tiên được dùng): catalog_dirs của workspace, hoặc, với một Release mà cấu hình workspace cấp thư mục riêng trong workspace.releases, thì các thư mục của Release đó; ngăn xếp kết thúc bằng thư mục có tên catalog ở gốc workspace nếu có. Một danh sách catalog_dirs được viết rỗng sẽ không đọc catalog cục bộ nào cả. |
--debug | false | Xuất chẩn đoán chi tiết dễ đọc cho người trên stderr — thời gian thực của từng giai đoạn và số lượng thực thể/phụ thuộc. Được ưu tiên hơn —quiet: đầu ra chi tiết luôn được xuất. Khác với —trace, vốn ghi các tệp trung gian theo từng nút, dạng máy đọc được, vào .trace/ |
--detail | false | Theo mặc định, build chỉ đọc và không in chi tiết phân giải nào. Khi bước pull chạy — vì —auto-pull được truyền vào hoặc workspace bật auto_pull — build điền lockfile trong tiến trình dù đã có lockfile hay chưa, và cờ này in ra, với mỗi thực thể được phân giải, việc mà lần điền đó đã làm: tải mới từ registry, dùng lại một ô cache, tìm thấy trong catalog cục bộ, được cung cấp từ bên trong tệp nhị phân của trình biên dịch, hoặc bên ngoài (Aggregate hay Manifest của chính Release, đọc từ tệp hoặc mục mà Release chỉ định). Khi không có bước pull nào chạy, cờ này in một dòng thông báo điều đó thay cho các dòng theo từng thực thể. Chỉ ra stdout; không được lưu lại |
--disable-plugin-cache | false | Bỏ qua cache biên dịch plugin lưu trên đĩa cho lần build này và biên dịch mới các guest plugin trong một cache trong bộ nhớ, bị hủy khi build kết thúc. Tắt theo mặc định, khi đó cache dùng chung trên đĩa được tái sử dụng giữa các lần build. Không thay đổi đầu ra được render |
--dry-run | false | Render Release và in ra những gì nó sẽ phát sinh thay vì ghi ra: đường dẫn dự kiến và nội dung của từng artifact được đưa ra stdout, còn thư mục đầu ra và lockfile được giữ nguyên. Các đầu vào bên ngoài hoạt động y hệt như trong một lần build thông thường — đầu vào đã pin được cung cấp từ kho định địa chỉ theo nội dung (và được điền lại theo digest khi thiếu blob), còn một lần render yêu cầu URL bên ngoài chưa pin sẽ dừng lại và nêu tên URL đó — nên những gì một lần chạy thử hiển thị chính là những gì một lần build sẽ ghi. Từ chối kết hợp với —auto-pull, —upgrade hoặc —trace, vì mỗi cờ này đều ghi — hãy chạy bước điền phụ thuộc, hoặc một lần build có trace, như một bước riêng. Có thể kết hợp với —policy-input, khi đó các tệp của cờ này là thứ duy nhất nó ghi |
--ir-graph | false | Ghi thêm đồ thị IR mà lần chạy này đã tính ra stdout, dưới dạng JSON, bên cạnh mọi thứ lệnh này vốn tạo ra. Các giá trị mà tác giả khai báo là nhạy cảm sẽ bị giữ lại khỏi đồ thị; truyền —unredacted để in chúng ra. Các artifact vẫn được ghi và bản tóm tắt vẫn được in; đồ thị được ghi trước cả hai |
--no-unsupported-field-warnings | false | Tắt nhóm cảnh báo trường không được hỗ trợ: các thông báo mà một target đưa ra cho thứ bạn đã viết nhưng nó không thể đáp ứng — một trường Workload mà nó không thể biểu diễn (như một target có độ trung thực thấp hơn, chẳng hạn compose) hoặc một annotation aggrega.ai/ mà nó không xử lý với loại đầu vào của nút. Các cảnh báo render khác vẫn hiển thị. Chỉ ảnh hưởng hiển thị; không thay đổi đầu ra được render |
--policy-input | — | Ghi vào thư mục này payload mà mỗi vai trò quản trị trao cho một plugin được gắn ở đó, dưới dạng một dòng JSON: đúng những gì bản build trao cho plugin, với mọi giá trị mà bản build giữ lại không cho plugin cũng đều được giữ lại. Với annotation-transform, label-transform và ir-verdict, tệp là tài liệu input mà một policy ở vai trò đó đọc. Với render-verdict, policy engine định hình lại payload trước khi policy đọc nó — documents của mỗi artifact được phân tích từ đó — nên một policy render-verdict trên engine tích hợp sẵn được kiểm thử trong một bản build, được gắn sao cho nó báo cáo ở mức warn hoặc info; với một plugin có .wasm do bạn tự build, aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json chạy nó trên tệp đó. Một vai trò không có gì được gắn cũng được ghi, dưới dạng payload mà một attachment không có nguồn và không có thiết lập sẽ nhận, nên có thể viết policy trước khi gắn nó. Mỗi vai trò được ghi vào <role>.json (annotation-transform, label-transform, ir-verdict, render-verdict); khi các attachment ở cùng một vai trò nhận các payload khác nhau — một attachment mang nguồn hoặc thiết lập riêng, hoặc một transform thay đổi những gì attachment tiếp theo đọc — thì mỗi attachment được ghi vào <role>.<position>.<plugin>.json thay vào đó, trong đó position đếm các attachment của vai trò đó từ 1 theo thứ tự cấu hình workspace liệt kê chúng, và plugin là đoạn cuối của tham chiếu plugin không kèm phiên bản, với mọi ký tự mà tên tệp không chứa được đều được thoát. Các tệp có những tên đó đã có trong thư mục sẽ bị thay thế và không có gì khác ở đó bị động đến. Các tệp được ghi dù bản build hoàn tất hay dừng lại, và một bản build dừng trước khi một vai trò chạy sẽ nêu tên từng vai trò mà nó không ghi tệp. Yêu cầu các tệp này không thay đổi artifact nào và phán quyết nào. Có thể kết hợp với —dry-run, khi đó nó chỉ ghi các tệp này và không gì khác: thư mục đầu ra và lockfile được giữ nguyên |
--progress | false | Buộc bật phần hiển thị tiến trình build ngay cả khi stderr không phải là terminal, in một dòng thuần cho mỗi bước khi bước đó hoàn tất, kèm thời gian. Mặc định là auto: danh sách kiểm tra giai đoạn tương tác chỉ hiển thị khi stderr là một terminal diễn giải được chuỗi escape, terminal không diễn giải được sẽ nhận các dòng thuần tương tự, còn đầu ra được chuyển hướng hoặc qua pipe thì không nhận gì. —quiet và —debug đều ghi đè —progress |
--quiet | false | Tắt phần hiển thị tiến trình build trên stderr. Không ảnh hưởng đến stdout. Được ưu tiên hơn —progress |
--release | — | Đường dẫn đến tệp YAML của Release (bắt buộc). Đường dẫn tương đối được phân giải theo thư mục bạn chạy lệnh, không theo gốc workspace. Khi thư mục đó không thuộc workspace nào và không có gốc nào được chỉ định, một đường dẫn tuyệt đối sẽ tìm workspace từ thư mục riêng của Release |
--trace | false | ghi các tệp trung gian theo từng nút vào .trace/ bên dưới gốc workspace, cạnh dist/, để kiểm tra sau sự cố |
--trace-unredacted | false | Ghi các giá trị được khai báo là nhạy cảm vào các tệp .trace/ thay cho văn bản |
--unredacted | false | In các giá trị mà tác giả khai báo là nhạy cảm thay vì giữ lại chúng. Bất cứ nơi nào đầu ra tới — terminal, pipe, tệp, bản ghi màn hình — khi đó sẽ chứa các giá trị đó ở dạng rõ. Chỉ tác động đến đồ thị mà —ir-graph ghi và không gì khác, nên nó yêu cầu —ir-graph; các tệp .trace/ dùng —trace-unredacted thay thế |
--upgrade | false | Biến bước auto-pull thành một lần làm mới toàn bộ: bỏ lockfile hiện có và phân giải lại mọi phụ thuộc từ trạng thái registry hiện tại, nâng mỗi phụ thuộc lên phiên bản cao nhất có sẵn thay vì tôn trọng các pin hiện có. Ngụ ý —auto-pull — khi dùng riêng, nó chạy một lần pull làm mới toàn bộ trước khi build. Nó không nhận target, nên không thể thu hẹp về một phụ thuộc: để áp dụng hoặc bỏ một pin duy nhất, hãy chạy aggrega pull —upgrade —release |
--verify-determinism | false | Render mọi nút hai lần và so sánh các byte được phát sinh, dừng build nếu hai lần render của bất kỳ nút nào khác nhau. Tắt theo mặc định. Dùng nó để xác nhận một provider render một cách tất định — đầu vào giống hệt cho ra đầu ra giống hệt từng byte — điều mà các đảm bảo về GitOps-diff và đầu ra giống hệt từng byte dựa vào |
--yes | false | Trả lời trước lời xác nhận của —upgrade, để dùng không tương tác. Cờ này chỉ tác động đến đúng lời nhắc đó và không gì khác: một lần build không làm mới sẽ không hỏi gì, nên truyền nó vào không thay đổi hành vi nào ở đó |